Recurring payments

(TODO: Improve the texts. That was migrate as it is from confluence)

This document has the purpose of aiding the payment gateway users on how to handle the recurring payment feature, by shining a light into all the available endpoints and explaining how to make proper use of them.

Endpoints

Method	Endpoint	Description	Allows Query Paramenters
GET	`/recurring`	Retrieves all the recurring payments that fall into the filtered query parameters	Yes
PATCH	`/recurring`	Receives an object in the body that replaces the properties of all the options that fall in the filtered query parameters	Yes
PATCH	`/recurrin/active`	Changes the status of all the filtered recurring payments to ACTIVE	Yes
PATCH	`/recurring/inactive`	Changes the status of all the filtered recurring payments to INACTIVE	Yes
POST	`/recurring/:paymentId`	Execute a recurring by recurring ID returned in the Payment Request.	No

All of the endpoints referred above allow the insertion of query parameters, these query parameters will then shape the way the requests are done in order to only apply to the subset of options that match the data passed in those query parameters.

(On the absence of query parameters then all of the entries will be fetched)

info

IMPORTANT NOTE - When executing a bulk PATCH on any of the endpoints it is important to double-check the query parameters before submitting, given that a wrong usage can lead to an irrecuperable (or close to it) loss of data.

Requests

Query Parameters

Below there is a screenshot of some of the fields that can be queried through the API, resorting to query parameters:

Body

Below there is a snippet of an example of a valid body request.

{
  "status": "ACTIVE",
  "payments": ["5ee90198881d2d6b5d2cc6d5"],
  "_id": "5ee90198881d2d6b5d2cc6d5",
  "amount": "000000800000",
  "cardHolderEmail": "[email protected]",
  "phone": "099999999",
  "locale": "en",
  "scopeId": "ef98bd59-3393-4ae3-b049-3567abe0f0df",
  "currencyCode": 200,
  "customFields1": "A",
  "customFields2": "B",
  "customFields3": "C",
  "paymentAccount": "default",
  "paymentMethod": "cc",
  "createdAt": "2020-06-16T17:30:00.561Z",
  "updatedAt": "2020-06-16T17:30:00.561Z",
  "cardNumber": "545454XXXXXX5454",
  "cardMonth": "12",
  "cardYear": "2020",
  "auto": false,
  "period": "",
  "start": "2020-06-16T17:30:34.108Z",
  "instance": "bolttech",
  "productName": "TESTE",
  "paymentProvider": "2c2p"
}

This body can be segmented to only alter the intended fields.

E.g.: If only the cardHolder would be eligible for a change the request body could be segmented to:

{
  "cardHolderEmail": "[email protected]"
}

Get All / Get Filtered

Request

Information	Description
Host	Provided by boltPay
Method	GET
Endpoint	`/recurring`
Params	One or more attribute of the example object (Not Required) - Used to filter results Ex.: scopeId `?scopeId=ec53eaee-0a3b-4399-9e8d-52d1899cc163`
Body	none

Response

[
  {
    "status": "ACTIVE",
    "payments": ["5ee90198881d2d6b5d2cc6d5"],
    "_id": "5ee90198881d2d6b5d2cc6d5",
    "amount": "000000800000",
    "cardHolderEmail": "[email protected]",
    "phone": "099999999",
    "locale": "en",
    "scopeId": "ef98bd59-3393-4ae3-b049-3567abe0f0df",
    "currencyCode": 200,
    "customFields1": "A",
    "customFields2": "B",
    "customFields3": "C",
    "paymentAccount": "default",
    "paymentMethod": "cc",
    "createdAt": "2020-06-16T17:30:00.561Z",
    "updatedAt": "2020-06-16T17:30:00.561Z",
    "cardNumber": "545454XXXXXX5454",
    "cardMonth": "12",
    "cardYear": "2020",
    "auto": false,
    "period": "",
    "start": "2020-06-16T17:30:34.108Z",
    "instance": "bolttech",
    "productName": "TESTE",
    "paymentProvider": "2c2p"
  },
  ...
]

Response with filter

Ex: [email protected]

[
  {
    "status": "ACTIVE",
    "payments": ["6065a3a05909245d0d749c58"],
    "_id": "6065a3a45909242620749c61",
    "amount": "000000064521",
    "cardHolderEmail": "[email protected]",
    "phone": "0932423432",
    "productName": "รถส่วนบุคคล",
    "locale": "th",
    "scopeId": "ec53eaee-0a3b-4399-9e8d-52d1899cc163",
    "currencyCode": 100,
    "customFields1": "a759c660-92d5-11eb-8073-6386826ee3b4",
    "customFields2": "8aff22dd-0a05-47aa-bfdf-5776e50ca251",
    "customFields3": "",
    "paymentAccount": "bki-account",
    "paymentMethod": "cc",
    "instance": "frank_stage_rc",
    "createdAt": "2021-04-01T10:42:40.043Z",
    "updatedAt": "2021-04-01T10:42:40.043Z",
    "paymentProvider": "2c2p",
    "auto": false,
    "start": "2021-04-01T10:42:44.463Z"
  },
  {
    "status": "ACTIVE",
    "payments": ["6065acd7590924ae26749c8b"],
    "_id": "6065acdc59092422c1749c94",
    "amount": "000000032314",
    "cardHolderEmail": "[email protected]",
    "phone": "0923423423",
    "productName": "มอเตอร์ไซค์ไฟฟ้า ทุก kWh",
    "locale": "th",
    "scopeId": "ec53eaee-0a3b-4399-9e8d-52d1899cc163",
    "currencyCode": 100,
    "customFields1": "6b865c00-92dc-11eb-8073-6386826ee3b4",
    "customFields2": "4d31482c-6b40-48b7-b1f9-3feae10549d4",
    "customFields3": "",
    "paymentAccount": "thaisri-account",
    "paymentMethod": "cc",
    "instance": "frank_stage_rc",
    "createdAt": "2021-04-01T11:21:59.667Z",
    "updatedAt": "2021-04-01T11:21:59.667Z",
    "paymentProvider": "2c2p",
    "auto": false,
    "start": "2021-04-01T11:22:04.049Z"
  },
  ...
]

Update

This method only updates one recurring payment, so be careful and make sure that the params filter return the expected recurring object.

info

For that always filter using the _id.

Request

Information	Description
Host	Provided by boltPay
Method	PATCH
Endpoint	`/recurring`
Params	One or more attribute of the example object (Not Required) - Used to filter results to be updated Ex.: _id `?_id=62a1d58014e1943500cc39b3`
Body	raw: Partial object with the attribute/attributes that have to be updated
Content-Type	`application/json`

Ex:

[PATCH] /recurring?_id=62a1d58014e1943500cc39b3

Body

{
  "amount": "000000087752"
}

Response

{
  "status": true,
  "result": {
    "status": "ACTIVE",
    "payments": ["62a1d57c14e1949562cc39a9"],
    "_id": "62a1d58014e1943500cc39b3",
    "amount": "000000087752",
    "cardHolderEmail": "[email protected]",
    "phone": "",
    "productName": "ประกันบ้านและทรัพย์สิน",
    "locale": "th",
    "scopeId": "ec53eaee-0a3b-4399-9e8d-52d1899cc163",
    "currencyCode": 100,
    "customFields1": "e5368d00-e7e4-11ec-8990-69318057730f",
    "customFields2": "60589400-98ce-48fb-a689-79701603c57d",
    "customFields3": "FR-TH-62a1d55aba68f",
    "customFields4": "",
    "paymentAccount": "dhipaya-account",
    "paymentMethod": "cc",
    "instance": "frank_stage_rc",
    "token": "b23caeeb120f73076ed8ef57a01cba49f1c0c57fda7c8542c892efae868bc2f0",
    "createdAt": "2022-06-09T11:11:56.504Z",
    "updatedAt": "2022-06-13T08:51:36.562Z",
    "__v": 0,
    "paymentProvider": "2c2p",
    "password": "37",
    "start": "2022-06-09T11:12:00.164Z"
  }
}

Active

As the UPDATE method, only one recurring payment is affected, so be careful and make sure that the params filter return the expected recurring object.

info

For that always filter using the _id.

Request

Information	Description
Host	Provided by boltPay
Method	PATCH
Endpoint	`/recurring/active`
Params	One or more attribute of the example object (Not Required) - Used to filter results to be updated Ex.: _id `?_id=5ee90198881d2d6b5d2cc6d5`
Body	none

Response

{
  "status": "ACTIVE",
  "payments": ["5ee90198881d2d6b5d2cc6d5"],
  "_id": "5ee90198881d2d6b5d2cc6d5",
  "amount": "000000800000",
  "cardHolderEmail": "[email protected]",
  "phone": "099999999",
  "locale": "en",
  "scopeId": "ef98bd59-3393-4ae3-b049-3567abe0f0df",
  "currencyCode": 200,
  "customFields1": "A",
  "customFields2": "B",
  "customFields3": "C",
  "paymentAccount": "default",
  "paymentMethod": "cc",
  "createdAt": "2020-06-16T17:30:00.561Z",
  "updatedAt": "2020-06-16T17:30:00.561Z",
  "cardNumber": "545454XXXXXX5454",
  "cardMonth": "12",
  "cardYear": "2020",
  "auto": false,
  "period": "",
  "start": "2020-06-16T17:30:34.108Z",
  "instance": "bolttech",
  "productName": "TESTE",
  "paymentProvider": "2c2p"
}

Inactive

As the UPDATE method, only one recurring payment is affected, so be careful and make sure that the params filter return the expected recurring object.

info

For that always filter using the _id.

Request

Information	Description
Host	Provided by boltPay
Method	PATCH
Endpoint	`/recurring/inactive`
Params	One or more attribute of the example object (Not Required) - Used to filter results to be updated Ex.: _id `?_id=5ee90198881d2d6b5d2cc6d5`
Body	none

Response

{
  "status": "INACTIVE",
  "payments": ["5ee90198881d2d6b5d2cc6d5"],
  "_id": "5ee90198881d2d6b5d2cc6d5",
  "amount": "000000800000",
  "cardHolderEmail": "[email protected]",
  "phone": "099999999",
  "locale": "en",
  "scopeId": "ef98bd59-3393-4ae3-b049-3567abe0f0df",
  "currencyCode": 200,
  "customFields1": "A",
  "customFields2": "B",
  "customFields3": "C",
  "paymentAccount": "default",
  "paymentMethod": "cc",
  "createdAt": "2020-06-16T17:30:00.561Z",
  "updatedAt": "2020-06-16T17:30:00.561Z",
  "cardNumber": "545454XXXXXX5454",
  "cardMonth": "12",
  "cardYear": "2020",
  "auto": false,
  "period": "",
  "start": "2020-06-16T17:30:34.108Z",
  "instance": "bolttech",
  "productName": "TESTE",
  "paymentProvider": "2c2p"
}

Execute Recurring Payment

Request

Information	Description
Host	Provided by boltPay
Method	POST
Endpoint	`/recurring/:paymentId`
Body	optional

Body is optional, meaning that you can either send new payment details to be used on the recurring payment or you can just leave it blank and details from initial payment (the one were the option "recurring" was set) will be used. Beware that not all payment detail are needed since most of the times we just want to define a new amount, so you can have a simpler payment payload like the following:

{
  "amount": "000000185003",
  "customFields1": "ABC",
  "customFields2": "DFG",
  "customFields3": "HIF",
  "callbackFrontendEndpoint": "",
  "callbackBackendEndpoint": ""
}

Response

When executing the recurrence endpoint, the payment gateway will generate a new payment based on the recurrence data. After that, the payment gateway will proceed with the payment process and return the generated payment code.

Success

{
  "status": true,
  "result": {
    "success": true,
    "status": "CONFIRMED",
    "message": "Approved",
    "customFields1": "YOUR_DATA",
    "customFields2": "YOUR_DATA",
    "customFields3": "YOUR_DATA",
    "paymentId": "601437c1f801896274a19aec",
    "currencyCode": "201",
    "amount": "8000.00",
    "invoiceNumber": "1611937744892abb9na",
    "bank": "BANK",
    "paymentMethod": "cc"
  }
}

Failure

{
  "status": false,
  "result": {
    "success": false,
    "status": "FAILED",
    "message": "Invalid Card Number",
    "customFields1": "YOUR_DATA",
    "customFields2": "YOUR_DATA",
    "customFields3": "YOUR_DATA",
    "paymentId": "60137beb4e6bc07fcffdeee1",
    "currencyCode": "201",
    "amount": "8000.00",
    "error": "Invalid Card Number",
    "paymentMethod": "cc"
  }
}

Endpoints​

Requests​

Query Parameters​

Body​

Get All / Get Filtered​

Request​

Response​

Response with filter​

Update​

Request​

Response​

Active​

Request​

Response​

Inactive​

Request​

Response​

Execute Recurring Payment​

Request​

Response​

Success​

Failure​

Endpoints

Requests

Query Parameters

Body

Get All / Get Filtered

Request

Response

Response with filter

Update

Request

Response

Active

Request

Response

Inactive

Request

Response

Execute Recurring Payment

Request

Response

Success

Failure