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 /api/v2/merchants/{mid}/orders/{orderId}

Example request¶

POST /api/v2/merchants/1570616552/orders/order_example_1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
   "amount": {
      "currency": "EUR",
      "amount": 10.50
   },
   "transactionChannel": "Web Online",
   "cardInfo": {
      "cardNumber": "4111111111111111",
      "cardExpiryDate": "12-2024"
   }
}

Example response¶

{
    "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.50,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "acquirerAuthorizationCode": "123456",
            "acquirerReferenceId": "622135",
            "acquirerAnswerCode": "00",
            "bankReferenceId": "622135",
            "bankAnswerCode": "00",
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "12-2024",
            "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 value by default is false, that will initiate an Authorize transaction. Set autoCapture to true to initiate a Debit transaction.

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.

Credential on File (CoF)¶

To indicate a transaction using CoF, use the storedCredentialInfo object.

See Credential on File for more details.

Example request¶

POST /api/v2/merchants/1570616552/orders/order_example_1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
   "amount": {
      "currency": "EUR",
      "amount": 10.50
   },
   "transactionChannel": "Web Online",
   "cardInfo": {
      "cardNumber": "4111111111111111",
      "cardExpiryDate": "12-2024"
   },
   "storedCredentialInfo": {
      "storedCredentialIndicator": "CIT_FIRST_TIME",
      "storedCredentialReason": "RECURRING"
   }
}

Example response¶

{
    "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.50,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "acquirerAuthorizationCode": "123456",
            "acquirerReferenceId": "622135",
            "acquirerAnswerCode": "00",
            "bankReferenceId": "622135",
            "bankAnswerCode": "00",
            "schemeReferenceId": "CIT_ID_PAYON_2010",
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "12-2024",
            "cvResponse": "",
            "cvAnswerCode": 2,
            "avsResponse": "",
            "avsAnswerCode": 3
        }
    ]
}

IBP, Redirect and eWallet¶

To initiate payments for IBP, Redirect or eWallet payment methods, a URL is generated during the InitiatePayment process that will allow the consumer to be redirected to the appropriate site. In order to get the final state of the payment, see Complete Payment.

Example request¶

POST /api/v2/merchants/1570616552/orders/order_example_1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
    "amount": {
        "amount": 10.50,
        "currency": "SEK"
    },
    "autoCapture": true,
    "paymentMethodId": 1,
    "redirectInfo": {
        "getUrl": "https://www.example.com/capture-response-from-bank",
        "postUrl": "https://www.example.com/capture-response-from-bank"
    },
    "transactionChannel": "Web Online"
}

Example response¶

{
    "mid": 1570616552,
    "orderId": "order_example_1",
    "orderAmount": 10.50,
    "fulfilmentAmount": 0,
    "capturedAmount": 0,
    "refundedAmount": 0,
    "currency": "SEK",
    "baseCurrency": "SEK",
    "baseOrderAmount": 10.50,
    "baseFulfilmentAmount": 0,
    "baseCapturedAmount": 0,
    "baseRefundedAmount": 0,
    "capturable": false,
    "cancelable": false,
    "refundable": false,
    "completable": true,
    "dccIndicator": false,
    "timestamp": "2020-03-13T10:16:23.047Z",
    "transactionReferences": [
        {
            "transactionId": 10442995701,
            "transactionTypeId": 108,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "InitiateDebit",
            "transactionDate": "2020-03-13T10:16:23.047Z",
            "transactionDesc": "Transaction Accepted",
            "statusCode": 0,
            "status": "Processed",
            "amount": 10.50,
            "currency": "SEK",
            "baseAmount": 10.50,
            "baseCurrency": "SEK",
            "paymentMethod": "Nordea SE",
            "paymentMethodId": 1,
            "bankReferenceId": "",
            "bankAnswerCode": "",
            "redirectMethod": "POST",
            "redirectUrl": "https://gfs.nb.se/e-betalning/direktbetalning",
            "redirectParameters": "<INPUT TYPE=HIDDEN NAME=\"NB_VERSION\" VALUE=\"0002\">\n<INPUT TYPE=HIDDEN NAME=\"NB_RCV_ID\" VALUE=\"83832893\">\n<INPUT TYPE=HIDDEN NAME=\"NB_STAMP\" VALUE=\"10442995701\">\n<INPUT TYPE=HIDDEN NAME=\"NB_DB_AMOUNT\" VALUE=\"10,50\">\n<INPUT TYPE=HIDDEN NAME=\"NB_DB_CUR\" VALUE=\"SEK\">\n<INPUT TYPE=HIDDEN NAME=\"NB_DB_REF\" VALUE=\"10442995701\">\n<INPUT TYPE=HIDDEN NAME=\"NB_RETURN\" VALUE=\"https://www.example.com/capture-response-from-bank\">\n<INPUT TYPE=HIDDEN NAME=\"NB_REJECT\" VALUE=\"https://www.example.com/capture-response-from-bank?STATUS=1&NB_STAMP=5230970501\">\n<INPUT TYPE=HIDDEN NAME=\"NB_CANCEL\" VALUE=\"https://www.example.com/capture-response-from-bank?STATUS=2&NB_STAMP=5230970501\">\n<INPUT TYPE=HIDDEN NAME=\"NB_HMAC\" VALUE=\"644BDB24EF29B48B9275B851567522DC\">\n<INPUT TYPE=HIDDEN NAME=\"NB_KVV\" VALUE=\"FF365893D899291C3BF505FB3175E880\">\n"
        }
    ]
}

Tokenization as a service¶

Use the StoreToken API to store payment instruments with Worldline. The token can be used directly in a transaction or referenced in a later transactions for e.g., subscriptions or returning customers.

The StoreToken currently supports tokenization of card payments details (card number and expiration date).

The token can be used multiple times, until the token has expired.

The service supports several modes of processing tokens, Multi-use and Single-use tokenization. This is configured during integration and by default, all integrations are Multi-use.

Single-use Token¶

The tokens belongs to one MerchantID. When calling for tokenization of a card that is already stored, with the same card number, a new token will be generated and returned.

The token returned by StoreToken (for Single-Use Token) will have a similar format as a TransactionId (64 bit integer).

Multi-Use Token¶

When calling for tokenization of a card that is already stored, with the same card number, the service will update the existing token with the new details and return the same Token.

Tokens belongs to the MerchantID that called for the tokenization, but in cases where you need to share the token between several MerchantIDs, this can be configured. Contact Worldline for setting up the configuration.

Token name¶

Worldline will generate a token name. The format of the name is by default similar to a card number, starting with 9000 and ending with the 4 last digits of the tokenized card number.

It is possible to set a token name, instead of having Worldline generating a token name. The Token name can be any string up to 35 characters.

Consideration for Client Side Encryption¶

For integrations that are using Client Side Encryption, the Tokenization Service will use the encrypted card information in the field EncryptedCardPayload.

Storing a token¶

The Token request is given by,

POST /api/v2/merchants/{mid}/tokens

The OrderId is passed in the request body, and must be unique.

The response is a transaction reference, where the most important information is

        "status": "Processed",
        "paymentMethod": "Visa",
        "paymentMethodId": 1001,
        "token": "9000033649121111",
        "maskedAccountNumber": "411111xxxxxx1111",
        "cardExpiryDate": "12-2024"

Example request¶

Tokens

POST /api/v2/merchants/1570616552/tokens HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
    "orderId": "order_example_1",
    "cardInfo": {
      "cardNumber": "4111111111111111",
      "expirationDate": "12-2024",
      "cardHolderName": "Firstname Lastname"
    }
  }

Example response¶

Tokens

{
    "transactionReferences": [
        {
            "transactionId": 10044016524,
            "transactionTypeId": 130,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "StoreToken",
            "transactionDate": "2020-03-12T08:38:50.348Z",
            "transactionDesc": "Transaction Accepted",
            "statusCode": 0,
            "status": "Processed",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "token": "9000033649121111",
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "12-2024"
        }
    ]
}

Strong Customer Authentication¶

3D Secure incorporates strong customer authentication by making better risk assessment decisions, thus providing higher authorization probability.

3DS 2.x has Frictionless flow and Challenge flow. It has three possible protocols: InitiateAuthentication, ContinueAuthentication and CompleteAuthentication. Based on the authenticationStatus from the response the subsequent workflow follows.

Most of the 3DS flows involves one or several calls between the consumer browser and the ACS and is not described in this section, it is therefore highly recommended that the detailed section on Strong customer authentication is reviewed.

Frictionless¶

When the Initiate Authentication response contains authentication status as SUCCESSFUL then it follows 3DS Frictionless. To the caller, this means that the returned cardAuthenticationInfo object must be provided with the initial payment request to be able to claim liability shift.

The Initiate Authentication request for 3DS 2.x is given by,

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

Example request¶

InitiateAuthentication

POST /api/v2/merchants/1570616552/orders/order_example_1/authentications HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
   "amount":{
      "amount":10.50,
      "currency":"EUR"
   },
   "cardInfo":{
      "cardNumber":"4111111111111111",
      "expirationDate":"12-2024"
   },
   "merchantUrl": "https://someurltoredirectbackto.com/callbacks"
}

Example response¶

InitiateAuthentication

{
    "mid": 1570616552,
    "orderId": "order_example_1",
    "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,
    "timestamp": "2020-02-21T09:49:08.164Z",
    "transactionReferences": [
        {
            "transactionId": 10042959346,
            "transactionTypeId": 155,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "InitiateAuthentication",
            "transactionDate": "2020-02-21T09:49:08.164Z",
            "transactionDesc": "Transaction Accepted",
            "statusCode": 0,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.50,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "12-2024",
            "cardAuthenticationInfo": {
                "xid": "MDAwMDAwMDAwMTAwNDI5NTkzNDY=",
                "cavv": "QUNTRU1Vd1BTV28kOj1Xe2VRSUc=",
                "eci": "5",
                "authRequired": "Y",
                "authenticationResult": "Y",
                "authenticationProtocolVersion": "3DS2.1.0",
                "authenticationDsTransId": "9913d29b-c02f-5f24-8000-00000000f01d"
            },
            "authenticationStatus": "SUCCESSFUL"
        }
    ]
}

Frictionless with 3D Method Data¶

When the Initiate Authentication response has CONTINUE as an authentication status and the subsequent status as SUCCESSFUL for Continue Authentication then it follows 3DS Frictionless with 3D Method. Merchant renders the HTML content of response attribute tDSMethodContent in an invisible iFrame for 2-3 seconds before calling continueauthentications

The Continue Authentication request for 3DS 2.x is given by,

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

Example request¶

InitiateAuthentication

POST /api/v2/merchants/1570616552/orders/order_example_1/authentications HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
    "amount": {
        "amount": 10.50,
        "currency": "EUR"
    },
    "cardInfo": {
        "cardNumber": "4111111111111111",
        "cardExpiryDate": "12-2024"
    },
    "merchantUrl": "https://someurltoredirectbackto.com/callbacks"
}

ContinueAuthentication

POST /api/v2/merchants/1570616552/orders/order_example_1/continueauthentications HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

Example response¶

InitiateAuthentication

{
    "mid": 1570616552,
    "orderId": "order_example_1",
    "orderAmount": 0,
    "fulfilmentAmount": 0,
    "capturedAmount": 0,
    "refundedAmount": 0,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "baseOrderAmount": 0,
    "baseFulfilmentAmount": 0,
    "baseCapturedAmount": 0,
    "baseRefundedAmount": 0,
    "capturable": false,
    "cancelable": false,
    "refundable": false,
    "completable": false,
    "dccIndicator": false,
    "timestamp": "2020-02-21T09:59:23.230Z",
    "transactionReferences": [
        {
            "transactionId": 10042958338,
            "transactionTypeId": 155,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "InitiateAuthentication",
            "transactionDate": "2020-02-21T09:59:23.230Z",
            "transactionDesc": "Continue with authentication",
            "statusCode": 26029,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.50,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "12-2024",
            "cardAuthenticationInfo": {
                "xid": "MDAwMDAwMDAwMTAwNDI5NTgzMzg=",
                "authRequired": "-",
                "authenticationResult": "-",
                "authenticationProtocolVersion": "3DS2.1.0",
                "authenticationDsTransId": "203d1fa7-d56b-54f8-8000-00000000f01f",
                "md": "MERCHANT_DATA",
                "tDSMethodContent": "<iframe id=\"tdsMmethodTgtFrame\" name=\"tdsMmethodTgtFrame\" style=\"width: 1px; height: 1px; display: none;\" src=\"javascript:false;\" xmlns=\"http://www.w3.org/1999/xhtml\">\n    <!--.-->\n</iframe><form id=\"tdsMmethodForm\" name=\"tdsMmethodForm\" action=\"https://dsx.modirum.com/dstests/ACSEmu2?handshake=1\" method=\"post\" target=\"tdsMmethodTgtFrame\" xmlns=\"http://www.w3.org/1999/xhtml\">\n    <input type=\"hidden\" name=\"3DSMethodData\" value=\"eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogIjIwM2QxZmE3LWQ1NmItNTRmOC04MDAwLTAwMDAwMDAwZjAxZiIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovLzM1LjIyOC44My4xNTcvL21kcGF5bXBpL01lcmNoYW50U2VydmVyP21uPVkmdHhpZD02MTQ3MSZkaWdlc3Q9M0M3VWdNcFlwMWJSOW82cEpRd20lMkZOZU0xT2lqVXNMNm1BTXdhdTlCQlhBJTNEIiB9\"/>\n    <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogIjIwM2QxZmE3LWQ1NmItNTRmOC04MDAwLTAwMDAwMDAwZjAxZiIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovLzM1LjIyOC44My4xNTcvL21kcGF5bXBpL01lcmNoYW50U2VydmVyP21uPVkmdHhpZD02MTQ3MSZkaWdlc3Q9M0M3VWdNcFlwMWJSOW82cEpRd20lMkZOZU0xT2lqVXNMNm1BTXdhdTlCQlhBJTNEIiB9\"/>\n</form><script type=\"text/javascript\" xmlns=\"http://www.w3.org/1999/xhtml\">\ndocument.getElementById(\"tdsMmethodForm\").submit();\n</script>"
            },
            "authenticationStatus": "CONTINUE"
        }
    ]
}

ContinueAuthentication

{
    "mid": 1570616552,
    "orderId": "order_example_1",
    "orderAmount": 0,
    "fulfilmentAmount": 0,
    "capturedAmount": 0,
    "refundedAmount": 0,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "baseOrderAmount": 0,
    "baseFulfilmentAmount": 0,
    "baseCapturedAmount": 0,
    "baseRefundedAmount": 0,
    "capturable": false,
    "cancelable": false,
    "refundable": false,
    "completable": false,
    "dccIndicator": false,
    "timestamp": "2020-02-21T10:03:52.021Z",
    "transactionReferences": [
        {
            "transactionId": 10042958342,
            "transactionTypeId": 166,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "ContinueAuthentication",
            "transactionDate": "2020-02-21T10:04:25.668Z",
            "refTransactionId": 10042958341,
            "transactionDesc": "Transaction Accepted",
            "statusCode": 0,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.50,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "12-2024",
            "cardAuthenticationInfo": {
                "xid": "MDAwMDAwMDAwMTAwNDI5NTgzNDE=",
                "cavv": "QUNTRU1VP0ZnaTE0YEZccyBzYjg=",
                "eci": "5",
                "authRequired": "Y",
                "authenticationResult": "Y",
                "authenticationProtocolVersion": "3DS2.1.0",
                "authenticationDsTransId": "5f091e85-8356-562e-8000-00000000f021"
            },
            "authenticationStatus": "SUCCESSFUL"
        }
    ]
}

Challenge¶

When the Initiate Authentication response contains authentication status as REQUIRED then it follows 3DS Challenge.

Once the REQUIRED response is received the consumer browser and ACS should negotiate consumer authentication before merchant can proceed with calling /completeauthentications. Referer to Strong customer authentication for details around this.

The Complete Authentication request for 3DS 2.x is given by,

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

Proceed with Complete Authentication. If the transaction is processed, the status SUCCESSFUL is received as an authentication status, else the status TRY_AGAIN is received.

Example request¶

InitiateAuthentication

POST /api/v2/merchants/1570616552/orders/order_example_1/authentications HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
    "amount": {
        "amount": 10.50,
        "currency": "EUR"
    },
    "cardInfo": {
        "cardNumber": "4111111111111111",
        "cardExpiryDate": "12-2024"
    },
    "merchantUrl": "https://someurltoredirectbackto.com/callbacks"
}

CompleteAuthentication

POST /api/v2/merchants/1570616552/orders/order_example_1/completeauthentications HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
    "authenticationResultParameter": "ewogICAiYWNzUmVmZXJlbmNlTnVtYmVyIiA6ICJBQ1NFbXUyIiwKICAgImFjc1RyYW5zSUQiIDogIjAwMDAwMDAwLTAwMDUtNWE1YS04MDAwLTAxNzA2NzM3NTdkNyIsCiAgICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogIjFiY2QzNTE4LTk3ZmItNWNkMC04MDAwLTAwMDAwMDAwZjAyMyIsCiAgICJ0cmFuc1N0YXR1cyIgOiAiWSIKfQ"
}

Example response¶

InitiateAuthentication

{
    "mid": 1570616552,
    "orderId": "order_example_1",
    "orderAmount": 0,
    "fulfilmentAmount": 0,
    "capturedAmount": 0,
    "refundedAmount": 0,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "baseOrderAmount": 0,
    "baseFulfilmentAmount": 0,
    "baseCapturedAmount": 0,
    "baseRefundedAmount": 0,
    "capturable": false,
    "cancelable": false,
    "refundable": false,
    "completable": false,
    "dccIndicator": false,
    "timestamp": "2020-02-21T10:10:32.073Z",
    "transactionReferences": [
        {
            "transactionId": 10042958344,
            "transactionTypeId": 155,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "InitiateAuthentication",
            "transactionDate": "2020-02-21T10:10:32.073Z",
            "transactionDesc": "Authentication required",
            "statusCode": 26016,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.50,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "12-2024",
            "cardAuthenticationInfo": {
                "xid": "MDAwMDAwMDAwMTAwNDI5NTgzNDQ=",
                "authRequired": "Y",
                "authenticationResult": "C",
                "authenticationProtocolVersion": "3DS2.1.0",
                "authenticationDsTransId": "bf1e2c8d-9088-52a6-8000-00000000f024",
                "md": "MERCHANT_DATA"
            },
            "authenticationStatus": "REQUIRED",
            "authenticationUrl": "https://dsx.modirum.com:443/dstests/ACSEmu2",
            "authenticationRedirectParameters": "{\"creq\":\"ewogICAiYWNzVHJhbnNJRCIgOiAiMDAwMDAwMDAtMDAwNS01YTVhLTgwMDAtMDE3MDY3M2EzOWMyIiwKICAgImNoYWxsZW5nZVdpbmRvd1NpemUiIDogIjA1IiwKICAgIm1lc3NhZ2VUeXBlIiA6ICJDUmVxIiwKICAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiYmYxZTJjOGQtOTA4OC01MmE2LTgwMDAtMDAwMDAwMDBmMDI0Igp9\",\"threeDSSessionData\":\"MERCHANT_DATA\",\"TermUrl\":\"https://somereturn.com/callback\"}",
            "authenticationRedirectMethod": "POST"
        }
    ]
}

CompleteAuthentication

{
    "mid": 1570616552,
    "orderId": "order_example_1",
    "orderAmount": 0,
    "fulfilmentAmount": 0,
    "capturedAmount": 0,
    "refundedAmount": 0,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "baseOrderAmount": 0,
    "baseFulfilmentAmount": 0,
    "baseCapturedAmount": 0,
    "baseRefundedAmount": 0,
    "capturable": false,
    "cancelable": false,
    "refundable": false,
    "completable": false,
    "dccIndicator": false,
    "timestamp": "2020-02-21T10:07:22.870Z",
    "transactionReferences": [
        {
            "transactionId": 10042958345,
            "transactionTypeId": 156,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "CompleteAuthentication",
            "transactionDate": "2020-02-21T10:12:44.612Z",
            "refTransactionId": 10042959355,
            "transactionDesc": "Transaction Accepted",
            "statusCode": 0,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.50,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "12-2024",
            "cardAuthenticationInfo": {
                "xid": "MDAwMDAwMDAwMTAwNDI5NTkzNTU=",
                "cavv": "QUNTRU1VamhjJmE/OllcJERoY2A=",
                "eci": "5",
                "authRequired": "Y",
                "authenticationResult": "Y",
                "authenticationProtocolVersion": "3DS2.1.0",
                "authenticationDsTransId": "1bcd3518-97fb-5cd0-8000-00000000f023"
            },
            "authenticationStatus": "SUCCESSFUL"
        }
    ]
}

Challenge with 3D Method Data¶

When the Initiate Authentication response contains CONTINUE as an authentication status and the subsequent status as REQUIRED for Continue Authentication then it follows 3DS Challenge with 3D Method.

Proceed with Complete Authentication. If the transaction is processed the status SUCCESSFUL is received as an authentication status, else the status TRY_AGAIN is received.

Example request¶

InitiateAuthentication

POST /api/v2/merchants/1570616552/orders/order_example_1/authentications HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
    "amount": {
        "amount": 10.50,
        "currency": "EUR"
    },
    "cardInfo": {
        "cardNumber": "4111111111111111",
        "cardExpiryDate": "12-2024"
    },
    "merchantUrl": "https://someurltoredirectbackto.com/callbacks"
}

ContinueAuthentication

POST /api/v2/merchants/1570616552/orders/order_example_1/continueauthentications HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

CompleteAuthentication

POST /api/v2/merchants/1570616552/orders/order_example_1/completeauthentications HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
   "authenticationResultParameter":"ewogICAiYWNzUmVmZXJlbmNlTnVtYmVyIiA6ICJBQ1NFbXUyIiwKICAgImFjc1RyYW5zSUQiIDogIjAwMDAwMDAwLTAwMDUtNWE1YS04MDAwLTAxNzA2NzQ2ZjUwMCIsCiAgICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogImY5MmI3NDczLWZjNTQtNWM1YS04MDAwLTAwMDAwMDAwZjAyNSIsCiAgICJ0cmFuc1N0YXR1cyIgOiAiWSIKfQ"
}

Example response¶

InitiateAuthentication

{
    "mid": 1570616552,
    "orderId": "order_example_1",
    "orderAmount": 0,
    "fulfilmentAmount": 0,
    "capturedAmount": 0,
    "refundedAmount": 0,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "baseOrderAmount": 0,
    "baseFulfilmentAmount": 0,
    "baseCapturedAmount": 0,
    "baseRefundedAmount": 0,
    "capturable": false,
    "cancelable": false,
    "refundable": false,
    "completable": false,
    "dccIndicator": false,
    "timestamp": "2020-02-21T10:27:27.424Z",
    "transactionReferences": [
        {
            "transactionId": 10042960003,
            "transactionTypeId": 155,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "InitiateAuthentication",
            "transactionDate": "2020-02-21T10:27:27.424Z",
            "transactionDesc": "Continue with authentication",
            "statusCode": 26029,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.50,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "12-2024",
            "cardAuthenticationInfo": {
                "xid": "MDAwMDAwMDAwMTAwNDI5NjAwMDM=",
                "authRequired": "-",
                "authenticationResult": "-",
               "authenticationProtocolVersion": "3DS2.1.0",
                "authenticationDsTransId": "bfbed979-489b-5650-8000-00000000f026",
                "md": "MERCHANT_DATA",
                "tDSMethodContent": "<iframe id=\"tdsMmethodTgtFrame\" name=\"tdsMmethodTgtFrame\" style=\"width: 1px; height: 1px; display: none;\" src=\"javascript:false;\" xmlns=\"http://www.w3.org/1999/xhtml\">\n    <!--.-->\n</iframe><form id=\"tdsMmethodForm\" name=\"tdsMmethodForm\" action=\"https://dsx.modirum.com/dstests/ACSEmu2?handshake=1\" method=\"post\" target=\"tdsMmethodTgtFrame\" xmlns=\"http://www.w3.org/1999/xhtml\">\n    <input type=\"hidden\" name=\"3DSMethodData\" value=\"eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogImJmYmVkOTc5LTQ4OWItNTY1MC04MDAwLTAwMDAwMDAwZjAyNiIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovLzM1LjIyOC44My4xNTcvL21kcGF5bXBpL01lcmNoYW50U2VydmVyP21uPVkmdHhpZD02MTQ3OCZkaWdlc3Q9WDdXekxPMmdBZVczWVlOZnVkZkxvQm1uVElYR1pxWVR3ZGJEMFJuQnhlMCUzRCIgfQ\"/>\n    <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogImJmYmVkOTc5LTQ4OWItNTY1MC04MDAwLTAwMDAwMDAwZjAyNiIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovLzM1LjIyOC44My4xNTcvL21kcGF5bXBpL01lcmNoYW50U2VydmVyP21uPVkmdHhpZD02MTQ3OCZkaWdlc3Q9WDdXekxPMmdBZVczWVlOZnVkZkxvQm1uVElYR1pxWVR3ZGJEMFJuQnhlMCUzRCIgfQ\"/>\n</form><script type=\"text/javascript\" xmlns=\"http://www.w3.org/1999/xhtml\">\ndocument.getElementById(\"tdsMmethodForm\").submit();\n</script>"
            },
            "authenticationStatus": "CONTINUE"
        }
    ]
}

ContinueAuthentication

{
    "mid": 1570616552,
    "orderId": "order_example_1",
    "orderAmount": 0,
    "fulfilmentAmount": 0,
    "capturedAmount": 0,
    "refundedAmount": 0,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "baseOrderAmount": 0,
    "baseFulfilmentAmount": 0,
    "baseCapturedAmount": 0,
    "baseRefundedAmount": 0,
    "capturable": false,
    "cancelable": false,
    "refundable": false,
    "completable": false,
    "dccIndicator": false,
    "timestamp": "2020-02-21T10:27:27.424Z",
    "transactionReferences": [
        {
            "transactionId": 10042960004,
            "transactionTypeId": 166,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "ContinueAuthentication",
            "transactionDate": "2020-02-21T10:29:33.244Z",
            "refTransactionId": 10042960003,
            "transactionDesc": "Authentication required",
            "statusCode": 26016,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.50,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "12-2024",
            "cardAuthenticationInfo": {
                "xid": "MDAwMDAwMDAwMTAwNDI5NjAwMDM=",
                "authRequired": "Y",
                "authenticationResult": "C",
                "authenticationProtocolVersion": "3DS2.1.0",
                "authenticationDsTransId": "bfbed979-489b-5650-8000-00000000f026"
            },
            "authenticationStatus": "REQUIRED",
            "authenticationUrl": "https://dsx.modirum.com:443/dstests/ACSEmu2",
            "authenticationRedirectParameters": "{\"creq\":\"ewogICAiYWNzVHJhbnNJRCIgOiAiMDAwMDAwMDAtMDAwNS01YTVhLTgwMDAtMDE3MDY3NGJhODU1IiwKICAgImNoYWxsZW5nZVdpbmRvd1NpemUiIDogIjA1IiwKICAgIm1lc3NhZ2VUeXBlIiA6ICJDUmVxIiwKICAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiYmZiZWQ5NzktNDg5Yi01NjUwLTgwMDAtMDAwMDAwMDBmMDI2Igp9\",\"TermUrl\":\"https://somereturn.com/callback\"}",
            "authenticationRedirectMethod": "POST"
        }
    ]
}

CompleteAuthentication

{
    "mid": 1570616552,
    "orderId": "order_example_1",
    "orderAmount": 0,
    "fulfilmentAmount": 0,
    "capturedAmount": 0,
    "refundedAmount": 0,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "baseOrderAmount": 0,
    "baseFulfilmentAmount": 0,
    "baseCapturedAmount": 0,
    "baseRefundedAmount": 0,
    "capturable": false,
    "cancelable": false,
    "refundable": false,
    "completable": false,
    "dccIndicator": false,
    "timestamp": "2020-02-21T10:24:21.983Z",
    "transactionReferences": [
        {
            "transactionId": 10042960002,
            "transactionTypeId": 156,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "CompleteAuthentication",
            "transactionDate": "2020-02-21T10:29:52.425Z",
            "refTransactionId": 10042959583,
            "transactionDesc": "Transaction Accepted",
           "statusCode": 0,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.50,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "02-2021",
            "cardAuthenticationInfo": {
                "xid": "MDAwMDAwMDAwMTAwNDI5NTk1ODM=",
                "cavv": "QUNTRU1VW3BMJV9NUCRFcyZ/alc=",
                "eci": "5",
                "authRequired": "Y",
                "authenticationResult": "Y",
                "authenticationProtocolVersion": "3DS2.1.0",
                "authenticationDsTransId": "f92b7473-fc54-5c5a-8000-00000000f025"
            },
            "authenticationStatus": "SUCCESSFUL"
        }
    ]
}

Order level vs Transaction level Payment processing¶

The recommended way to integrate with the Payment REST API is by working with orders.

The Merchant configuration applies for both the Order level and Transaction level. The Request and the Response body follows the same schema.

Transaction level payment management is an advance way to handle more complex use cases. It mandates the merchant to explicitly specify the reference transaction of each operation. The Payments REST API will validate the correctness of the referred transaction.

Cancel order¶

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

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

Example request¶

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

Example response¶

{
    "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.50,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "acquirerAnswerCode": "00",
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "12-2024",
            "cvResponse": "",
            "cvAnswerCode": 4,
            "avsResponse": "",
            "avsAnswerCode": 4
        }
    ]
}

Cancel transaction¶

Advanced topic

This section explains the payment processing on transaction level. Transaction level payment processing allows granular control and is subjected to specific validations.

Cancelling a specific Authorize transaction is done by referring to the Authorize Transaction.

POST /api/v2/transactions/{transactionId}/cancels

Example request¶

POST /api/v2/transactions/5986909891/cancels HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

Example response¶

{
    "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.50,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "acquirerAnswerCode": "00",
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "12-2024",
            "cvResponse": "",
            "cvAnswerCode": 4,
            "avsResponse": "",
            "avsAnswerCode": 4
        }
    ]
}

Capture order¶

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

POST /api/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¶

POST /api/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¶

{
    "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.50,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "12-2024",
            "cvResponse": "",
            "cvAnswerCode": 4,
            "avsResponse": "",
            "avsAnswerCode": 4
        }
    ]
}

Capture transaction¶

Advanced topic

This section explains the payment processing on transaction level. Transaction level payment processing allows granular control and is subjected to specific validations.

Capturing a specific Authorize transaction is done by referring to the Authorize Transaction.

POST /api/v2/transactions/{transactionId}/captures

Example request¶

POST /api/v2/transactions/5986908782/captures HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

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

Example response¶

{
    "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.50,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "12-2024",
            "cvResponse": "",
            "cvAnswerCode": 4,
            "avsResponse": "",
            "avsAnswerCode": 4
        }
    ]
}

Refund order¶

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

POST /api/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¶

POST /api/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¶

{
    "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.50,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "12-2024",
            "cvResponse": "",
            "cvAnswerCode": 4,
            "avsResponse": "",
            "avsAnswerCode": 4
        }
    ]
}

Refund to a different card¶

Processing a Refund to a different card number/ card scheme is possible by specifying the card details or token.

Example request¶

POST /api/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"
   },
   "cardInfo": {
      "cardNumber": "5555555555554444",
      "cardExpiryDate": "06-2026"
   }
}

Example response¶

{
    "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.50,
            "baseCurrency": "EUR",
            "paymentMethod": "MasterCard",
            "paymentMethodId": 1002,
            "maskedAccountNumber": "555555xxxxxx4444",
            "cardExpiryDate": "06-20206",
            "cvResponse": "",
            "cvAnswerCode": 4,
            "avsResponse": "",
            "avsAnswerCode": 4
        }
    ]
}

Refund using a token¶

Processing a Refund using a token referencing to a card number is possible by specifying the token details.

Example request¶

POST /api/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"
   },
   "token": "9000037590314444"
}

Example response¶

{
    "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.50,
            "baseCurrency": "EUR",
            "paymentMethod": "MasterCard",
            "paymentMethodId": 1002,
            "token":"9000037590314444",
            "maskedAccountNumber": "555555xxxxxx4444",
            "cardExpiryDate": "06-2026",
            "cvResponse": "",
            "cvAnswerCode": 4,
            "avsResponse": "",
            "avsAnswerCode": 4
        }
    ]
}

Refund to a bank account¶

Processing a Refund to a consumer's bank account is possible by specifying the bank details.

It is only valid for Redirect Payment and EFT.

Example request¶

POST /api/v2/merchants/1570616552/orders/order_example/refunds HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
   "amount": {
      "amount": 10.50,
      "currency": "EUR"
   },
   "bankBillingInfo": {
      "iban": "SE123456",
      "swiftBIC": "ESSESESS"
   }
}

Example response¶

{
    "mid": 1570616552,
    "orderId": "order_example",
    "orderAmount": 0,
    "fulfilmentAmount": 0,
    "capturedAmount": 0,
    "refundedAmount": 10.50,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "baseOrderAmount": 0,
    "baseFulfilmentAmount": 0,
    "baseCapturedAmount": 0,
    "baseRefundedAmount": 10.50,
    "capturable": false,
    "cancelable": false,
    "refundable": false,
    "completable": false,
    "dccIndicator": false,
    "timestamp": "2020-01-13T08:09:29.487Z",
    "transactionReferences": [
        {
            "transactionId": 10194108019,
            "transactionTypeId": 65,
            "mid": 1570616552,
            "orderId": "order_example",
            "transactionType": "Payout",
            "transactionDate": "2020-01-13T08:09:29.487Z",
            "transactionDesc": "OK",
            "statusCode": 0,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.50,
            "baseCurrency": "EUR",
            "paymentMethod": "SEPA",
            "paymentMethodId": 3502
        }
    ]
}

Refund transaction¶

Advanced topic

This section explains the payment processing on transaction level. Transaction level payment processing allows granular control and is subjected to specific validations.

Refunding a specific transaction is done by referring to a Capture or Debit Transaction.

POST /api/v2/transactions/{transactionId}/refunds

Example request¶

POST /api/v2/transactions/5986909904/refunds HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

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

Example response¶

{
    "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.50,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "maskedAccountNumber": "411111xxxxxx1111",
            "cardExpiryDate": "12-2024",
            "cvResponse": "",
            "cvAnswerCode": 4,
            "avsResponse": "",
            "avsAnswerCode": 4
        }
    ]
}

Complete Payment¶

Complete Payment supports redirect payment methods. The request will trigger a real-time check to get the latest transaction status from third parties. E.g. Banks.

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

Example request¶

POST /api/v2/merchants/1570616552/orders/order_example_1/completes HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
    "redirectParameterString": "A=X&B=Y"
}

Example response¶

{
    "mid": 1570616552,
    "orderId": "order_example_1",
    "orderDetailDescription": "detailed desc",
    "orderDescription": "description",
    "orderAmount": 10.50,
    "fulfilmentAmount": 10.50,
    "capturedAmount": 10.50,
    "refundedAmount": 0.00,
    "currency": "SEK",
    "baseCurrency": "SEK",
    "baseOrderAmount": 10.50,
    "baseFulfilmentAmount": 10.50,
    "baseCapturedAmount": 10.50,
    "baseRefundedAmount": 0.00,
    "capturable": false,
    "cancelable": false,
    "refundable": true,
    "completable": false,
    "dccIndicator": false,
    "timestamp": "2020-03-13T10:16:23.047Z",
    "transactionReferences": [
        {
            "transactionId": 10442995789,
            "transactionTypeId": 109,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "Debit",
            "transactionDate": "2020-03-13T10:18:15.163Z",
            "refTransactionId": 10442995701,
            "transactionDesc": "Transaction Accepted",
            "statusCode": 0,
            "status": "Processed",
            "amount": 10.50,
            "currency": "SEK",
            "baseAmount": 10.50,
            "baseCurrency": "SEK",
            "paymentMethod": "Nordea SE",
            "paymentMethodId": 1
        }
    ]
}

Complete transaction¶

Advanced topic

This section explains the payment processing on transaction level. Transaction level payment processing allows granular control and is subjected to specific validations.

Completing a specific transaction is done by referring to an InitiateAuthorize or InitiateDebit Transaction.

POST /api/v2/transactions/{transactionId}/completes

Example request¶

POST /api/v2/transactions/1234567890/completes HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
    "redirectParameterString": "A=X&B=Y"
}

Example response¶

{
    "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,
    "timestamp": "2020-01-10T15:56:29.454Z",
    "transactionReferences": [
        {
            "transactionId": 10442995796,
            "transactionTypeId": 109,
            "mid": 1570616552,
            "orderId": "order_example_1",
            "transactionType": "Debit",
            "transactionDate": "2020-01-10T15:56:38.503Z",
            "refTransactionId": 1234567890,
            "transactionDesc": "Transaction Accepted",
            "statusCode": 0,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.50,
            "baseCurrency": "EUR",
            "paymentMethod": "CCAvenue",
            "paymentMethodId": 28
        }
    ]
}

Get order¶

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

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

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

Example request¶

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

Example response¶

{
    "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": "12-2024",
            "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": "12-2024",
            "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": "12-2024",
            "cvResponse": "",
            "cvAnswerCode": 2,
            "avsResponse": "",
            "avsAnswerCode": 3
        }
    ]
}

Original Credit (Credit without reference)¶

Original credit is a special transaction type which allows a refund without referring to an earlier payment. The orderId must be unique for this transaction type.

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

Example request¶

POST /api/v2/merchants/1570616552/orders/order_example/originalcredits HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
   "amount": {
      "currency": "EUR",
      "amount": 10.50
   },
   "cardInfo": {
      "cardNumber": "4111111111111111",
      "cardExpiryDate": "12-2024"
   }
}

Example response¶

{
    "mid": 1570616552,
    "orderId": "order_example",
    "orderAmount": 0.00,
    "fulfilmentAmount": 0.00,
    "capturedAmount": 0.00,
    "refundedAmount": 10.50,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "baseOrderAmount": 0.00,
    "baseFulfilmentAmount": 0.00,
    "baseCapturedAmount": 0.00,
    "baseRefundedAmount": 10.50,
    "capturable": false,
    "cancelable": false,
    "refundable": false,
    "completable": false,
    "dccIndicator": false,
    "timestamp": "2020-01-08T14:03:03.144Z",
    "transactionReferences": [
        {
            "transactionId": 10040895226,
            "transactionTypeId": 7,
            "mid": 1570616552,
            "orderId": "order_example",
            "transactionType": "OriginalCredit",
            "transactionDate": "2020-01-08T14:04:13.578Z",
            "transactionDesc": "Transaction Accepted",
            "statusCode": 0,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.50,
            "baseCurrency": "EUR",
            "paymentMethod": "Visa",
            "paymentMethodId": 1001,
            "maskedAccountNumber": "411111xxxxx1111",
            "cardExpiryDate": "12-2024"
        }
    ]
}

Payout to a bank account¶

Payout is a special transaction type which allows a refund to a Consumer's bank account without referring to an earlier payment. The orderId must be unique for this transaction type.

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

Example request¶

POST /api/v2/merchants/1570616552/orders/order_example/originalcredits HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer 573cec25a87526dcceacad786bbbba83b1a5172

{
   "amount": {
      "amount": 10.50,
      "currency": "EUR"
   },
   "bankBillingInfo": {
      "iban": "SE123456",
      "swiftBIC": "ESSESESS"
   },
   "paymentMethodId": 3502
}

Example response¶

{
    "mid": 1570616552,
    "orderId": "order_example",
    "orderAmount": 0,
    "fulfilmentAmount": 0,
    "capturedAmount": 0,
    "refundedAmount": 10.50,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "baseOrderAmount": 0,
    "baseFulfilmentAmount": 0,
    "baseCapturedAmount": 0,
    "baseRefundedAmount": 10.50,
    "capturable": false,
    "cancelable": false,
    "refundable": false,
    "completable": false,
    "dccIndicator": false,
    "timestamp": "2020-01-13T08:09:29.487Z",
    "transactionReferences": [
        {
            "transactionId": 10194108019,
            "transactionTypeId": 65,
            "mid": 1570616552,
            "orderId": "order_example",
            "transactionType": "Payout",
            "transactionDate": "2020-01-13T08:09:29.487Z",
            "transactionDesc": "OK",
            "statusCode": 0,
            "status": "Processed",
            "amount": 10.50,
            "currency": "EUR",
            "baseAmount": 10.50,
            "baseCurrency": "EUR",
            "paymentMethod": "SEPA",
            "paymentMethodId": 3502
        }
    ]
}