Booking Gateway

Documentation

Introduction

Sathapana Bank Connect allows Partners to integrate and be transparent to the gateway below

Partner can use their own iframe & Design as they wanted.


How to integrate

I. Subsequent Flow

One-time pay, authorize or capture

•          Step 1: Customers place an order on your website or app.

•          Step 2: You initiate an order from your server/app

•          Step 3: Your server created a session with Sathapana Bank Connect.

•          Step 4: Your website or app renders iframe that builds with Tokenex (hosted iframe) and gets the Tokenex iframe response

•          Step 5: Customer fills out Card Number.

•          Step 6: After filling Tokenex response data into the iframe

•          Step 7: Update the token response from Tokenex into the session with Sathapana Bank Connect API

•          Step 8: Authenticate 3ds and 3ds2 with Sathapana Bank Connect Api

•          Step 9: Authorize or Pay with Sathapana Bank Connect API

•          Step 10: (only if you authorize instead of paying in step 9) Capture with Sathapana Bank Connect API

II. Get Started

Before we get started partner needs to get ready and have this information.

Credentials provided by Sathapana Bank

•          Tokenex Token

•          Tokenex Id

•          Merchant Username

•          Merchant Password

•          Merchant Id

Additional tech stacks

•          Server

•          Custom iframe with tokenex (see: how to)

•          https domain for production

III. How to integrate

Normal payment process only one time, but in this payment are included with 2 types of payment. Full Payment or Partial Payment.

•          Full Payment is meant if the customer pays one time with the full amount

•          Partial Payment is meant if the customer pays partially

i. Process Flow

1) Create a Session

Before making a payment, we need to open the session

POST /gateway/<MERCHANT_ID>/session/create
Authorization: Basic <Marchant Basic Auth>
Parameters
<MERCHANT_ID> received from SPNB
Responses
{
    "merchant": "M03",
    "result": "SUCCESS",
    "session": {
        "aes256Key": "+U2nkvpZiKEzpF1kHpRJReKEK7SfhwfWdAQkoW5KO6E=",
        "authenticationLimit": 5,
        "id": "SESSION0002132724216F07415104L2",
        "updateStatus": "NO_UPDATE",
        "version": "63ce676e01"
    }
}

2) Add Source of Fund (Card result from iFrame)

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>
Parameters
<MERCHANT_ID> received from Satapana Bank
<SESSION_ID> ID you received from the previous step (see Create Session)
Body
{
  "order": {
    "id": "string",
    "amount": 10,
    "currency": "USD"
  },
  "sourceOfFunds": {
    "token": "string", // From Tokenex 
    "expiryMonth": 12, // From iFrame
    "expiryYear": 24 // From iFrame
  }
}
Responses
{
  "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"
  }
}

3) Authenticate

Once you add the Source of Fund, you should be able to pay or authorize; however, in the certain Country or Card required 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>
Parameters
<MERCHANT_ID> received from Sathapana Bank
<SESSION_ID> ID you received from the Create Session Step(see Create Session)
Body
{
  "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 redirect a post request after finishing Authentication acceptVersions: We can enforce 3ds1 only, but the default is 3DS1, 3DS2

Responses
{
  "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"
  }
}

4) Pay (Full Payment)

Once you add the Source of Fund, you should be able to pay; however, if you have had authorize before coming in this step you should get the transaction.id from the redirectUrl which called after being authenticated.


Parameters
<MERCHANT_ID> received from Sathapana Bank
<SESSION_ID> ID you received from the previous step (see 1. Create Session)
Body
{
  "order": {
    "id": "string",
    "amount": 100,
    "currency": "USD"
  },
  "authentication": {
    "transactionId": "string"
  },
  "session": {
    "id": "string"
  }
}
authentication.transactionId: This is the transactionId you received from the previous step (see 2. Authenticate)
authentication.transactionId: is not required if you don’t need 3ds1

Responses
{
  "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"
  }
}

4) Pay (Full Payment)

Once you add the Source of Fund, you should be able to pay; however, if you have had authorize before coming in this step you should get the transaction.id from the redirectUrl which called after being authenticated.


POST /gateway/<MERCHANT_ID>/session/<SESSION_ID>/authorize
Authorization: Basic <Marchant Basic Auth>
Parameters
<MERCHANT_ID> received from Sathapana Bank
<SESSION_ID> ID you received from the previous step (see 1. Create Session)
Body
{
  "order": {
    "id": "string",
    "amount": 100,
    "currency": "USD"
  },
  "authentication": {
    "transactionId": "string"
  },
  "session": {
    "id": "string"
  }
}
authentication.transactionId: the transaction.id from Authentication step (see 3)
authentication.transactionId: is not required if you don’t need 3ds1

Responses
{
  "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"
  }
}

6) Capture (Partial Payment)

Once you authorize the Order, you should be able to capture some amount that is equal to or less than the Authorize Amount; however, if you capture the same amount as the amount that Authorize, you should consider calling Pay (Full Payment) instead.

POST /gateway/<MERCHANT_ID>/session/<SESSION_ID>/capture
Authorization: Basic <Marchant Basic Auth>
Parameters
<MERCHANT_ID> received from Sathapana Bank
<SESSION_ID> ID you received from the previous step (see 1. Create Session)
Body
{
  "order": {
    "id": "string"
  },
  "transaction": {
    "amount": 50,
    "currency": "USD"
  },
  "session": {
    "id": "string"
  }
}
transaction.amount: the transaction.amount must be less than or equal to the Authorize Amount

Responses
{
  "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": 100,
    "totalCapturedAmount": 50,
    "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"
  }
}

7) Void

Once you authorize the Order, you should be able to void the transaction in case a customer wanted to cancel their order.

POST /gateway/<MERCHANT_ID>/session/<SESSION_ID>/void
Authorization: Basic <Marchant Basic Auth>
Parameters
<MERCHANT_ID> received from Sathapana Bank
<SESSION_ID> ID you received from the previous step (see 1. Create Session)
Body
{
    "order": {
        "id": "string"
    },
    "originalTransactionId" : "string"
}
originalTransactionId: the transaction.id from the authorized order

{
  "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": 100,
    "totalCapturedAmount": 50,
    "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"
  }
}

8) Refund

After Pay or Capture, you should be able to refund. The refund amount for is less than or equal to the amount that is paid or captured.

POST /gateway/<MERCHANT_ID>/session/<SESSION_ID>/void
Authorization: Basic <Marchant Basic Auth>
Parameters
<MERCHANT_ID> received from Sathapana Bank
<SESSION_ID> ID you received from the previous step (see 1. Create Session)
Body
{
    "order": {
        "id": "{{order_id}}"
    },
    "transaction": {
        "amount": 10,
        "currency": "USD"
    }
}
transaction.amount: the transaction.amount must be less than or equal to the Paid Amount
{
  "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": 100,
    "totalCapturedAmount": 50,
    "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"
  }
}