Documentation
Card on File (CoF) allow the Card holder to authorize the merchant to store their Cards token which can be used for future payments without having a customer enter card details. Using the Saved token, transactions can be initiated by consumers or merchants ( or scheduled or recurring payments) depending on business needs.
There are many reasons to use the Card on File. The most common use case is to save their card for future payment or daily usage just like in Grab or Uber. For example, a customer wanted to save their card online and then use it later to pay without having to fill out the card every time they wanted to pay.
Before making adding a card similarity we need to open the session
POST /gateway/<MERCHANT_ID>/session/create
Authorization: Basic <Marchant Basic Auth>
<MERCHANT_ID> received from Sathapana Bank
{
"merchant": "M03",
"result": "SUCCESS",
"session": {
"aes256Key": "+U2nkvpZiKEzpF1kHpRJReKEK7SfhwfWdAQkoW5KO6E=",
"authenticationLimit": 5,
"id": "SESSION0002132724216F07415104L2",
"updateStatus": "NO_UPDATE",
"version": "63ce676e01"
}
}
After a session is created, we will have to add agreement.id in order to use it for pay with recurring. The agreement id should be unique per customer as they have to bind it with cardToken in the future.
POST /gateway/<MERCHANT_ID>/session/<SESSION_ID>/agreement
Authorization: Basic <Marchant Basic Auth>
<MERCHANT_ID> received from Sathapana Bank
<SESSION_ID> ID you received from the previous step (see Create Session)
{
"agreement": {
"id": "{{agreement_id}}",
"type": "RECURRING",
"expiryDate": "{{agreement_expiryDate}}",
"minimumDaysBetweenPayments": "{{agreement_minimumDaysBetweenPayments}}"
}
}
{
"merchant": "string",
"result": "string",
"version": "string",
"session": {
"id": "string",
"updateStatus": "string",
"version": "string"
},
"order": {
"expiryDate": "string",
"id": "string",
"minimumDaysBetweenPayments": "string",
"type": "string",
"authenticationStatus": "string",
"creationTime": "string",
"currency": "string",
"lastUpdatedTime": "string",
"merchantCategoryCode": "string",
"status": "string",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"sourceOfFunds": {
"provided": {
"card": {
"brand": "string",
"expiry": {
"month": 0,
"year": 0
},
"fundingMethod": "string",
"number": "string",
"scheme": "string"
}
},
"type": "CARD"
},
"response": {
"gatewayCode": "string",
"gatewayRecommendation": "string"
}
}
Once you received Card Token and YY/MM from tokenex iFrame ( see how to), you should be able to update the session via this API
POST /gateway/<MERCHANT_ID>/session/<SESSION_ID>/card
Authorization: Basic <Marchant Basic Auth>
<MERCHANT_ID> received from Sathapana Bank
<SESSION_ID> ID you received from the previous step (see Create Session)
{
"order": {
"id": "string",
"amount": 10,
"currency": "USD"
},
"sourceOfFunds": {
"token": "string", // From Tokenex
"expiryMonth": 12, // From iFrame
"expiryYear": 24 // From iFrame
}
}
{
"merchant": "string",
"result": "string",
"version": "string",
"session": {
"id": "string",
"updateStatus": "string",
"version": "string"
},
"order": {
"expiryDate": "string",
"id": "string",
"minimumDaysBetweenPayments": "string",
"type": "string",
"authenticationStatus": "string",
"creationTime": "string",
"currency": "string",
"lastUpdatedTime": "string",
"merchantCategoryCode": "string",
"status": "string",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"sourceOfFunds": {
"provided": {
"card": {
"brand": "string",
"expiry": {
"month": 0,
"year": 0
},
"fundingMethod": "string",
"number": "string",
"scheme": "string"
}
},
"type": "CARD"
},
"response": {
"gatewayCode": "string",
"gatewayRecommendation": "string"
}
}
Once you add the Source of Fund, you should be able to pay or authorize; however, in the certain Country or Cardrequired to authenticate before making a payment.
As for authenticate it has two types: 3DS1 and 3DS2.
Once you request the authenticate you should receive the authentications response below and you have to submit the redirectHtml into your iFrame and don’t forget to save the transaction.id in order to proceed the next step such as Pay or Authorize
POST /gateway/<MERCHANT_ID>/session/<SESSION_ID>/authenticate
Authorization: Basic <Marchant Basic Auth>
<MERCHANT_ID> received from Sathapana Bank
<SESSION_ID> ID you received from the Create Session Step(see Create Session)
{
"order": {
"id": "string",
"amount": 10,
"currency": "USD"
},
"sourceOfFunds": {
"token": "string", // From Tokenex
"expiryMonth": 12, // From iFrame
"expiryYear": 24 // From iFrame
},
"authRedirectUrl": "{{authRedirectUrl}}",
"acceptVersions": "3DS1, 3DS2"
}
authRedirectUrl is the URL that redirects a post request after finishing Authentication
acceptVersions: We can enforce 3ds1 only, but the default is 3DS1, 3DS2
{
"authentication": {
"3ds2": {
"acsEci": "string",
"authenticationToken": "string",
"transactionId": "string"
},
"3ds1": {
"paResStatus": "string",
"veResEnrolled": "string"
},
"payerInteraction": "string",
"redirect": {
"domainName": "string"
},
"redirectHtml": "string",
"version": "string"
},
"transaction": {
"acquirer": {
"merchantId": "string"
},
"amount": 0,
"authenticationStatus": "string",
"currency": "string",
"id": "string",
"type": "string"
},
"timeOfLastUpdate": "string",
"timeOfRecord": "string",
"response": {
"gatewayCode": "string",
"gatewayRecommendation": "string"
}
}
Once you add the Source of Fund, you should be able to verify; however, if you have had authorization before coming into this step you should get the transaction.id from the redirectUrl which is called after being authenticated.
POST /gateway/<MERCHANT_ID>/transaction/verify
Authorization: Basic <Marchant Basic Auth>
<MERCHANT_ID> received from Sathapana Bank
<SESSION_ID> ID you received from the previous step (see 1. Create Session)
{
"order": {
"id": "{{order_id}}",
"currency": "{{order_currency}}"
},
"session": {
"id": "{{session_id}}"
}
}
authentication.transactionId: the transaction.id from Authentication step (see 3)
authentication.transactionId: is not required if you don’t need 3ds1
{
"merchant": "string",
"result": "string",
"version": "string",
"session": {
"id": "string",
"updateStatus": "string",
"version": "string"
},
"agreement": {
"expiryDate": "string",
"id": "string",
"minimumDaysBetweenPayments": "string",
"type": "string"
},
"order": {
"expiryDate": "string",
"id": "string",
"minimumDaysBetweenPayments": "string",
"type": "string",
"authenticationStatus": "string",
"creationTime": "string",
"currency": "string",
"lastUpdatedTime": "string",
"merchantCategoryCode": "string",
"status": "string",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"sourceOfFunds": {
"provided": {
"card": {
"brand": "string",
"expiry": {
"month": 0,
"year": 0
},
"fundingMethod": "string",
"number": "string",
"scheme": "string"
}
},
"type": "CARD"
},
"authentication": {
"3ds2": {
"acsEci": "string",
"authenticationToken": "string",
"transactionId": "string"
},
"3ds1": {
"paResStatus": "string",
"veResEnrolled": "string"
},
"payerInteraction": "string",
"redirect": {
"domainName": "string"
},
"redirectHtml": "string",
"version": "string"
},
"transaction": {
"acquirer": {
"merchantId": "string"
},
"amount": 0,
"authenticationStatus": "string",
"currency": "string",
"id": "string",
"type": "string"
},
"timeOfLastUpdate": "string",
"timeOfRecord": "string",
"response": {
"gatewayCode": "string",
"gatewayRecommendation": "string"
}
}