Payment API Migration from v1 to v2

This document helps our clients to migrate payment APIs from the v1 version to v2.

In Brick, We have launched our new API version(v2). Our v2 version has

  • More reliable and secure
  • Faster response
  • Highly scalable
  • Better response structure

Our APIs(v2) are callback-based APIs, So if you have not set up a callback URL till now, Please set it frombrick dashboard.

So, In v2(Callback-based APIs), Once you hit any Brick API, You will get two responses.

  • Sync(Real-time response) - Once you call any API then, In real-time Brick will send an accepted response. So it means that your request is accepted. parameters. Structure of success and error cases are below.
{
  "status": 200,
  "data": {
    "message": "We have received your request and are processing it, please check your callback URL for transaction status",
    "otherFields":"XXXX"
  },
  "metaData": {
    "source": "API",
    "entity": "Payment"
  },
  "error": null
}
{ 
           "status" : XXX,        
           “error”:{
                    "code": {{brick_unique_error_code}}, 
                    "message": {{description_of_error}}, 
                    "action": {{further_action}},
                    "reason": {{Actual_reason_for_error}}
          }, 
          “metaData”:{
                    "source": {{API/Widget/Dashboard/SDK/Portal}}, 
                    "entity": "Payment"
         },
         "data":null 
 }
  • Async(Callback-based response) - Once Brick has completed the requested transaction, Brick will send the transaction completion as response over the callback URL. Structure of success and error cases are below.
{
  "status": 200,
  "data": {
    "message": "We have received your request and are processing it, please check your callback URL for transaction status",
    "id": "asdasd123123asdasd",
    "type": "disbursement",
    "attributes": {
      "referenceId": "referenceId-1",
      "description": "decription-1",
      "amount": "10000",
      "status": "completed",
      "createdAt": "2022-07-21T13:49:39.752+07:00",
      "disbursementMethod": {
        "type": "bank_transfer",
        "bankAccountNo": "12345678",
        "bankShortCode": "BCA",
        "bankAccountHolderName": "PROD ONLY"
      }
    }
  },
  "metaData": {
    "source": "API",
    "entity": "Payment"
  },
  "error": null
}
{
  "status": 200,
  "data": {
    "message": "We have received your request and are processing it, please check your callback URL for transaction status",
    "id": "asdasd123123asdasd",
    "type": "disbursement",
    "attributes": {
      "referenceId": "referenceId-1",
      "description": "decription-1",
      "amount": "10000",
      "status": "failed",
      "createdAt": "2022-07-21T13:49:39.752+07:00",
      "disbursementMethod": {
        "type": "bank_transfer",
        "bankAccountNo": "12345678",
        "bankShortCode": "BCA",
        "bankAccountHolderName": "PROD ONLY"
      }
    }
  },
  "metaData": {
    "source": "API",
    "entity": "Payment"
  },
  "error": null
}
{ 
           "status" : XXX,        
           “error”:{
                   "code": {{brick_unique_error_code}}, 
                   “job_id”:”11111111eeeee3e3”
                   "message": {{description_of_error}}, 
                   "action": {{further_action}},
                   "reason": {{Actual_reason_for_error}}
          }, 
          “metaData”:{
                   "source": {{API/Widget/Dashboard/SDK/Portal}}, 
                   "entity": "Payment"
         },
         "data":null 
 }

API Mapping from v1 to v2

Auth APIs

V1

Method in v1

V2

Method in v2

/v1/auth/token

Get

/v2/payments/auth/token

Get

Account Verification

V1

Method in v1

V2

Method in v2

/v1.1/payments/bank-account-validation

Post

/v2/payments/gs/bank-account-validation

Get

Disbursement APIs

V1

Method in V1

V2

Method in V2

/v1.1/payments/disbursements

Post

/v2/payments/gs/disbursements

Post

/v1.1/payments/disbursements/

Get

/v2/payments/gs/disbursements

Get

VA APIs(Coming Soon)

V1

Method in V1

V2

Method in V2

/v1/payments/open-va

Post

/v2/payments/gs/va/open

Post

/v1/payments/open-va/retrieve/

Get

/v2/payments/gs/va/open

Get

v1/payments/open-va/status/

Get

/v2/payments/gs/va/open/status

Post

/v1/payments/close-va

Post

/v2/payments/gs/va/close

Post

/v1/payments/close-va/retrieve

Get

/v2/payments/gs/va/close

Get

/v1/payments/close-va/status/

Get

/v2/payments/gs/va/close/status

Post