SUBSCRIPTION SERVICE API

Documentation

I. Introduction
II. Sequence Flow by Steps
- Option 1: One-time pay, authorize or capture
- Option 2: Recurring or Card on File
III. Get Started
IV. How to integrate

I. Introduction
II. Sequence Flow by Steps
- Option 1: One-time pay, authorize or capture
- Option 2: Recurring or Card on File
III. Get Started
IV. How to integrate

I. Introduction

Sathapana Connect is the transparent gateway that proxies into MPGS within the bank in order to associate with PCI Compliance. Sathapana Connect allows Partners to integrate and be transparent to the gateway with the following instruction.

II. Sequence Flow by Steps

Option 1: 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 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 pay in step 9) Capture with Sathapana Bank Connect API

Option 2: Recurring or Card on File

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 SPNB Connect

Step 4 - Adding agreementId into session (agreement id MUST random per customer)

Step 5: Your website or app renders iframe that build with Tokenex (hosted iframe) and get the tokenex iframe response

Step 6: Customer fills Card Number

Step 7: After filling Tokenex response data into the iframe

Step 8: Update the tokenex response from tokenex into session with SPNB Connect api

Step 9: Authenticate 3ds and 3ds2 with SPNB Connect Api Step 10: Verify the transaction with session by SPNB Connect Api

III. Get Started

Before we get started, Partners need to get ready and have this information. Credentials provided by Sathapana:

• 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

IV. How to integrate

For developers, if you are familiar with swagger and understand the full flow can skip this step.

IV.1 One-time Payment (Full or Partial)

Introduction

This section will guide you through the process of integrating with Sathapana Connect API to perform one-time payment (full or partial).

Use Cases

• There are many reasons to use One Time Pay. The most common use case is to purchase a product at one time, so that the Partner can give the product to the customer and get paid online.

• Full Payment is happening almost everywhere in our everyday life. For example, a customer wants to buy a simple thing online and then pays for it for the total amount using a Credit/Debit Card.

• Partial Payment is happening in a certain case only. For example, a customer wants to buy a simple thing online and then pay for it partially until the product arrives at the hand of the customer then they will complete the full amount of payment.

Process Flow

1. Create a Session

Before making a payment, we need to open the session

POST /gateway/<MERCHANT_ID>/session/create
Authorization: Basic <Merchant 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 <Merchant Basic Auth>

Parameters

<MERCHANT_ID> received from Sathapana Bank 
<SESSION_ID> ID you received from the previous step (see Create Session)

Body

{
  "order": {
    "id": "string",
    "amount": 100,
    "currency": "USD"
  },
  "authentication": {
    "transactionId": "string"
  }, "session": {
    "id": "string"
  } 
}

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 then 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<Merchant Basic Auth>

Responses


<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 authorization before coming in this step you should get the transaction.id from the redirectUrl which is called after being authenticated.

POST /gateway/<MERCHANT_ID>/session/<SESSION_ID>/pay 
  Authorization: Basic <Merchant 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"
    }
  }

5a. Authorize (Partial Payment)

Once you add the Source of Fund, you should be able to pay; 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>/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"
    }
  }

5b. 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"
  }
}

6. 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"
  }
}

7. 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"
  }
}

Add Card on File