One time Payment (Full or Partial)

Introduction

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

Use Cases

There are many reasons to use One Time Pay. The most common use case is to purchase a product one time, so that 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 arrived 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 <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 Sathapana 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 received 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.

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

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

Sathapana Gateway

One time Payment (Full or Partial)

Introduction

Use Cases

Process Flow

1. Create a Session

Parameters

Responses

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

Parameters

Body

Responses

3. Authenticate

Parameters

Body

Responses

4. Pay (Full Payment)

Parameters

Body

Responses

5a. Authorize (Partial Payment)

Parameters

Body

Responses

5b. Capture (Partial Payment)

Parameters

Body

Responses

6. Void

Parameters

Body

7. Refund

Parameters

Body