Skip to content

Payment REST API - Server

Initiate Payment

To initiate a payment for a new order, send POST request to the below path where {mid} is your merchant id and {orderId} is your reference to the order.

POST /v2/merchants/{mid}/orders/{orderId}

Example request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
POST /v2/merchants/1570616552/orders/order_example_1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
  "orderDescription": "description",
  "orderDetailDescription": "detailed desc",
  "paymentMethodId": 1000,
  "amount": {
    "currency": "EUR",
    "amount": 10.50
  },
  "autoCapture": false,
  "transactionChannel": "Web Online",
  "cardInfo": {
    "cardNumber": "4111111111111111",
    "expirationDate": "12-2024"
  },
  "cardVerificationInfo": {
    "cvCode": "123",
    "cvCodeState": "USED"
  }
}

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
{
    "mid": 1570616552,
    "orderId": "order_example_1",
    "orderDetailDescription": "detailed desc",
    "orderDescription": "description",
    "orderAmount": 10.50,
    "fulfilmentAmount": 10.50,
    "capturedAmount": 0.00,
    "refundedAmount": 0.00,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "baseOrderAmount": 10.50,
    "baseFulfilmentAmount": 10.50,
    "baseCapturedAmount": 0.00,
    "baseRefundedAmount": 0.00,
    "capturable": true,
    "cancelable": true,
    "refundable": false,
    "completable": false,
    "dccIndicator": false,
    "transactionReferences": [
        {
            "transactionId": 5986908782,
            "transactionTypeId": 1,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "Authorize",
            "transactionDate": "2019-10-04T14:05:26.927Z",
            "transactionDesc": "Transaction accepted",
            "statusCode": 0,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.5,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "acquirerAuthorizationCode": "123456",
            "acquirerReferenceId": "622135",
            "acquirerAnswerCode": "00",
            "bankReferenceId": "622135",
            "bankAnswerCode": "00",
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "2024-12",
            "cvResponse": "",
            "cvAnswerCode": 2,
            "avsResponse": "",
            "avsAnswerCode": 3
        }
    ]
}

Auto Capture

Use the flag autoCapture to determine whether the transaction is to be executed as an Authorize or Debit. The default value is false.

Recurring payments

To indicate that a transaction is recurring or not, use the recurringInfo object.

Tokenization

Referencing a tokenized card

Use a previously stored card by referencing the name of the token in the payment request.

To tokenize a card

Set createToken to true to store a card number during the Initiate Payment transaction call.

See Tokenization for other methods for tokenization.

Fraud Screening

To determine overall fraud screening behavior, use fraudControl.fraudScreening.

fraudScreening options Explanation
Screen Activate fraud screening.
Bypass Disable fraud screening.
Passive Fraud screening active, but ignore result.
Field Name Value Explanation
fraudScreeningPreAuth true Fraud screen prior to the processing of the transaction. This is the default behavior.
fraudScreeningPreAuth false Fraud screen after sending the transaction to the acquirer.
fraudScreeningOn3DSLiabilityShift true Fraud screen transaction even after successful 3DSecure liability shift.
fraudScreeningOn3DSLiabilityShift false Do not fraud screen transaction after successful 3DSecure liability shift. This is the default behavior.
fraudScreeningActionOnHold PASSED Override when the fraud screening provider returns HOLD.
fraudScreeningActionOnHold BLOCKED Do not override the fraud screening provider's response.

CVV, CVC screening

Set cardVerificationInfo.cvCodeState to USED when you pass cardVerificationInfo.cvCode.

AVS Screening

Address Validation System is activated when the issuing bank supports it. In order to enable, cardVerificationInfo.useAVS should be set to true. AVS uses addressLine1, city, zipCode under billingInfo.contactInfo object.

Payment control parameters

Set transactionChannel to indicate how the transaction details are collected, e.g. Web Online for a regular online transaction.

Set merchantInfo.posId to one of the pre-configured Point Of Sale IDs. Only use this field if you are configured for multiple posIDs.

Authorization type

Set cardInfo.authorizationType to define authorization type. The default value is UNDEFINED. Visa and MasterCard both supports PRE_AUTHORIZATION. However, Visa does not support FINAL_AUTHORIZATION.

Originating Account Type

originatingAccountType overrides the default card issue type by indicating the type of account to charge for the transaction when possible. The default is UNSPECIFIED. CHEQUE_ACCOUNT uses the card as a debit card. CREDIT_FACILITY uses the card as a credit card.

Cancel order

To cancel an order, send a POST request to the below path where {mid} is your merchant id and {orderId} is your reference to your order. Send empty body in the request.

POST /v2/merchants/{mid}/orders/{orderId}/cancels

Example request

1
2
3
4
POST /v2/merchants/1570616552/orders/order_example_1/cancels HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
    "mid": 1570616552,
    "orderId": "order_example_1",
    "orderDetailDescription": "detailed desc",
    "orderDescription": "description",
    "orderAmount": 0.00,
    "fulfilmentAmount": 0.00,
    "capturedAmount": 0.00,
    "refundedAmount": 0.00,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "baseOrderAmount": 0.00,
    "baseFulfilmentAmount": 0.00,
    "baseCapturedAmount": 0.00,
    "baseRefundedAmount": 0.00,
    "capturable": false,
    "cancelable": false,
    "refundable": false,
    "completable": false,
    "dccIndicator": false,
    "transactionReferences": [
        {
            "transactionId": 5986909900,
            "transactionTypeId": 4,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "Cancel",
            "transactionDate": "2019-10-04T14:33:18.848Z",
            "refTransactionId": 5986909891,
            "transactionDesc": "Transaction accepted",
            "statusCode": 0,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.5,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "acquirerAnswerCode": "00",
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "2024-12",
            "cvResponse": "",
            "cvAnswerCode": 4,
            "avsResponse": "",
            "avsAnswerCode": 4
        }
    ]
}

Capture order

To capture an order, send a POST request to the below path where {mid} is your merchant id and {orderId} is your reference to your order.

POST /v2/merchants/{mid}/orders/{orderId}/captures

The default amount to capture is the FulfilmentAmount that is already successfully authorized.

Partial capture is supported for the authorized amount.

Multiple captures and over captures are supported if configured.

If an amount is specified, the currency has to be the same currency as used in the previous transaction on the order.

Example request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
POST /v2/merchants/1570616552/orders/order_example_1/captures HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
  "amount" : {
    "amount": 10.50,
    "currency": "EUR"
  }
}

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
{
    "mid": 1570616552,
    "orderId": "order_example_1",
    "orderDetailDescription": "detailed desc",
    "orderDescription": "description",
    "orderAmount": 10.50,
    "fulfilmentAmount": 10.50,
    "capturedAmount": 10.50,
    "refundedAmount": 0.00,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "baseOrderAmount": 10.50,
    "baseFulfilmentAmount": 10.50,
    "baseCapturedAmount": 10.50,
    "baseRefundedAmount": 0.00,
    "capturable": false,
    "cancelable": false,
    "refundable": true,
    "completable": false,
    "dccIndicator": false,
    "transactionReferences": [
        {
            "transactionId": 5986909881,
            "transactionTypeId": 3,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "Capture",
            "transactionDate": "2019-10-04T14:19:34.264Z",
            "refTransactionId": 5986908782,
            "transactionDesc": "Transaction accepted",
            "statusCode": 0,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.5,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "2024-12",
            "cvResponse": "",
            "cvAnswerCode": 4,
            "avsResponse": "",
            "avsAnswerCode": 4
        }
    ]
}

Refund order

To refund an order, send a POST request to the below path where {mid} is your merchant id and {orderId} is your reference to your order.

POST /v2/merchants/{mid}/orders/{orderId}/refunds

By default, if there is no amount and currency in the request, the amount that is refunded will be set to that of the order CaptureAmount.

Partial refund is supported, if the order has a single capture or a debit transaction. The processing currency of the refund request has to be same as the currency of the order.

Multiple partial refunds are allowed but the with the same limitation as above.

Example request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
POST /v2/merchants/1570616552/orders/order_example_1/refunds HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
  "amount": {
    "amount": 10.50,
    "currency": "EUR"
  }
}

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
{
    "mid": 1570616552,
    "orderId": "order_example_1",
    "orderDetailDescription": "detailed desc",
    "orderDescription": "description",
    "orderAmount": 10.50,
    "fulfilmentAmount": 10.50,
    "capturedAmount": 10.50,
    "refundedAmount": 10.50,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "baseOrderAmount": 10.50,
    "baseFulfilmentAmount": 10.50,
    "baseCapturedAmount": 10.50,
    "baseRefundedAmount": 10.50,
    "capturable": false,
    "cancelable": false,
    "refundable": false,
    "completable": false,
    "dccIndicator": false,
    "transactionReferences": [
        {
            "transactionId": 5986909909,
            "transactionTypeId": 5,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "Credit",
            "transactionDate": "2019-10-04T14:41:38.157Z",
            "refTransactionId": 5986909904,
            "transactionDesc": "Transaction accepted",
            "statusCode": 0,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.5,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "2024-12",
            "cvResponse": "",
            "cvAnswerCode": 4,
            "avsResponse": "",
            "avsAnswerCode": 4
        }
    ]
}

Get order

To get an order details, send a GET request to the below path where {mid} is your merchant id and {orderId} is your reference to your order.

GET /v2/merchants/{mid}/orders/{orderId}

The GET response includes all the transactions in the scope of the order.

Example request

1
2
3
4
GET /v2/merchants/1570616552/orders/order_example_1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
{
    "mid": 1570616552,
    "orderId": "order_example_1",
    "orderDetailDescription": "detailed desc",
    "orderDescription": "description",
    "orderAmount": 10.50,
    "fulfilmentAmount": 10.50,
    "capturedAmount": 10.50,
    "refundedAmount": 10.50,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "baseOrderAmount": 10.50,
    "baseFulfilmentAmount": 10.50,
    "baseCapturedAmount": 10.50,
    "baseRefundedAmount": 10.50,
    "capturable": false,
    "cancelable": false,
    "refundable": false,
    "completable": false,
    "dccIndicator": false,
    "transactionReferences": [
        {
            "transactionId": 5986909909,
            "transactionTypeId": 5,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "Credit",
            "transactionDate": "2019-10-04T14:41:38.157Z",
            "refTransactionId": 5986909904,
            "transactionDesc": "Transaction accepted",
            "statusCode": 0,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.5,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "2024-12",
            "cvResponse": "",
            "cvAnswerCode": 4,
            "avsResponse": "",
            "avsAnswerCode": 4
        },
        {
            "transactionId": 5986909904,
            "transactionTypeId": 3,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "Capture",
            "transactionDate": "2019-10-04T14:38:52.752Z",
            "refTransactionId": 5986909903,
            "transactionDesc": "Transaction accepted",
            "statusCode": 0,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.5,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "2024-12",
            "cvResponse": "",
            "cvAnswerCode": 4,
            "avsResponse": "",
            "avsAnswerCode": 4
        },
        {
            "transactionId": 5986909903,
            "transactionTypeId": 1,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "Authorize",
            "transactionDate": "2019-10-04T14:38:43.410Z",
            "transactionDesc": "Transaction accepted",
            "statusCode": 0,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.5,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "acquirerAuthorizationCode": "123456",
            "acquirerReferenceId": "228748",
            "acquirerAnswerCode": "00",
            "bankReferenceId": "228748",
            "bankAnswerCode": "00",
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "2024-12",
            "cvResponse": "",
            "cvAnswerCode": 2,
            "avsResponse": "",
            "avsAnswerCode": 3
        }
    ]
}