Documentation
Sign UpLog In

Create Virtual Account via API

🚧

Prepare your account first

Before start this process, make sure you have check prepare your account section.

1. Generate public access token

Public access token is authentication token that will be used in further API call in payment out and accept payment APIs. This public access token generated using your API credential Client ID and Client Secret that you get from preparation section.

Put Client ID and Client Secret in header of the authentication API to generate the public access token like this :

Example :

curl -u client ID:client Secret https://sandbox.onebrick.io/v2/payments/auth/token

Process above will give you response like this and you get your public access token and ready to use it in the next process.

{
  "status": 200,
  "error": null,
  "metaData": {
    "source": "API",
    "entity": "Payment"
  },
  "data": {
    "message": "Access token is valid for 5 minutes and can use one time only",
    "accessToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxODQ3IiwiY29sb3VyIjoiIzMzMzMzMyIsInJvbGUiOlsiVVNFUiJdLCJuYW1lIjoiQnJpY2siLCJpc3MiOiJCcmljayIsImV4cCI6MTY1NzA4ODgzOSwiaWF0IjoxNjU3MDg4NTM5LCJqdGkiOiIyZTZmZTIwOS0yN2ZiLTQ0MjctOTI5Mi1lNThiYzMyMDUyMzkiLCJ0cyI6MTY1NzA4ODUzOTg1N30.gexikMhPVvS8z2j9muHhSAZb_TrkUAn4BDWIvOJLZDE",
    "issuedAt": "2022-07-06T13:22:19.857147",
    "expiresAt": "2022-07-06T13:27:19.857147"
  }
}

This API gives you a public access token that is only valid to be used 1 time and only for the next 5 minutes. If expired, you need to generate new public access token.

2. Generate VA

Next you can generate VA by calling generate VA endpoint. There are different endpoints for open and close VA, see sample bellow for the differences.

  • To generate open VA, you need to input data like bank type, reference ID, and display name.
  • To generate close VA, you need to input data like bank type, reference ID, display name, expiration time, and description.

Open VA

For simplicity you you can use example data to API call below :

curl --location --request POST 'https://sandbox.onebrick.io/v2/payments/gs/va/open' \
--header 'publicAccessToken: Bearer {{public-access-token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "bankShortCode": "MANDIRI",
    "referenceId": "Brick12345",
    "displayName": "BRICK"
}'

If process of generate VA success, you will see the response below and share the VA number to your customers.

{
  "status": 200,
  "data": {
    "message": "We have successfully generated the open VA",
    "id": "OP_b123123123asdas1231231123",
    "referenceId": "Brick12345",
    "bankShortCode": "MANDIRI",
    "accountNo": "1304300000003243",
    "displayName": "IKN-BRICK"
  },
  "metaData": {
    "source": "API",
    "entity": "Payment"
  },
  "error": null
}

At this point, the virtual account number is active and waiting for payment from the customers.

Close VA

For simplicity you you can use example data to API call below :

curl --location --request POST 'https://sandbox.onebrick.io/v2/payments/gs/va/close' \
--header 'publicAccessToken: Bearer {{public-access-token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 15000,
    "referenceId": "brick12345",
    "expiredAt": "60",
    "description": "Test Initial VA Close",
    "bankShortCode": "MANDIRI",
    "displayName": "BRICK"
}'

If process of generate VA success, you will see the response below and share the VA number to your customers.

{
  "status": 200,
  "data": {
    "message": "We have successfully generated the close VA",
    "id": "CL_asd123asd2322313asss2223321",
    "referenceId": "brick12345",
    "description": "Test Initial VA Close",
    "amount": "15000",
    "status": "pending",
    "createdAt": "2023-04-10T13:33:03.000+07:00",
    "expiredAt": "2023-04-10T14:34:03.000+07:00",
    "bankShortCode": "MANDIRI",
    "accountNo": "23096000000108142",
    "displayName": "BRICK"
  },
  "metaData": {
    "source": "API",
    "entity": "Payment"
  },
  "error": null
}

At this point, the virtual account number is active and waiting for payment from the customers.

3. Getting the callback status

Virtual account number will be active and waiting for the customer payment. Once customer transfer money to that virtual account number, bank system will send notification to Brick system and Brick system will pass the callback status from bank to your designated VA callback URL.

For virtual account, we will send callback twice :

  • When payment is made (status = “paid”)
  • When the fund settlement is done in each bank (status = “completed”)

Below is the sample of the virtual account callback data :

{
  "data": {
    "id": "OP_123456i12i1i123u123",
    "referenceId": "Dodo123456",
    "amount": "10000.0",
    "status": "paid",
    "createdAt": "2023-03-28T10:29:48.000+07:00",
		"paymentId": "PAY_b123b123b123b123b123b123bb1",
		"bankShortCode": "MANDIRI",
    "accountNo": "8804995730945965",
    "displayName": "BRICK"
  }
}

{
  "data": {
    "id": "OP_123456i12i1i123u123",
    "referenceId": "Dodo123456",
    "amount": "10000.0",
    "status": "completed",
    "createdAt": "2023-03-28T10:29:48.000+07:00",
		"paymentId": "PAY_b123b123b123b123b123b123bb1",
		"bankShortCode": "MANDIRI",
    "accountNo": "8804995730945965",
    "displayName": "BRICK"
  }
}

If process of payment out valid, you will see the response below that showing the payment out status as processing.

📘

Testing callback in sandbox

Callbacks are sent when there are changes in virtual account status. You will receive the callback automatically in production, but in sandbox, because there is no real transaction happening, how callbacks are triggered is different.

You need to call our endpoint so this endpoint will send update status to your callback URL. See this section to see how to test virtual account in sandbox.

Updated 12 months ago