Create Payment Link via API

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

1. Generate public access token

The Public Access Token serves as the authentication key for accessing the Payment Out and Accept Payment APIs. This token is generated using your unique API credentials, namely the Client ID and Client Secret, obtained during the preparation phase.

To generate the Public Access Token, simply include your Client ID and Client Secret in the header of the authentication API request. Here's how you can do it:

Example :

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

Upon completion of the process described above, you will receive a response containing your Public Access Token. This token serves as your authentication credential, enabling you to proceed to the next stage of the integration seamlessly.

{
  "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 Payment Link

Now that you have obtained your Public Access Token, you're all set to utilize it in the generation of your Payment Link API. Follow the steps below to initiate the process:

Endpoint: Utilize the Payment Link API endpoint to create payment links programmatically.
Authentication: Include your Public Access Token in the header of the API request for authentication.
Request: Specify the required parameters such as amount, currency, and optional description in your API call.
Response: Upon successful creation, you'll receive a response containing essential details including the unique payment link ID and its corresponding URL.
Let's proceed to generate your Payment Link API with the specified request and response parameters.

Request

To create a payment link via the Payment Link API, you need to include the following parameters in your request:

curl --location '{{url}}/v2/payments/gs/payment-link' \
--header 'publicAccessToken: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRob3JpemVkIjp0cnVlLCJleHAiOjE2OTQ0OTk5NzcsImlkIjo2MjMsIm5hbWUiOiJJcWkgRHVtbXkiLCJ1c2VyIjoicmF5aGFuLnNoaWRxaUBvbmVicmljay5pbyJ9.JvthCL6jexIhNGvyOyOv1v6S9vlVSe7gTcGeBKyo6DE' \
--form 'files=@"/path/to/file"' \
--form 'referenceId="testhalo"' \
--form 'amount="50000"' \
--form 'description="something"' \
--form 'endUserName="iqitest2"' \
--form 'endUserPhoneNumber="+62834343434"' \
--form 'endUserEmail="[email protected]"'\
--form 'endUserAddress="Jalan Tulodong bawah"' \
--form 'pin="1234"' \
--form 'redirectUrl="https://google.com"'

{
	"files" : [],
	"amount" : 500000,
	"referenceId" : "payment123",
	"description" : "Batting Glove",
	"endUserName" : "Daviga",
	"endUserPhoneNumber" : "+62819859238232",
	"endUserEmail" : "[email protected]",
	"endUserAddress" : "Jalan Tulodong bawah",
	"pin" : "1234",
	"redirectUrl" : "https://onebrick.io"
}

Upon successful creation of the payment link via the Payment Link API, you will receive a response containing the following key details:

{
  "status": 200,
	"data" : {
		"paymentLinkPath" : "/payment-link/F4B3UUU1GgTzhc35j7p4GdlirhFgo5ubzcqDHB9rwRtuzFxCdCwCush7z0yXcxsz4Vm2K23bS6e6peVD8KNtqg%3D%3D",
		"expiredAt" : "2023-08-09T12:00:00+07:00",
		"amount" : 500000,
		"referenceId" : "test-paymentlink-2023-08",
    "status": "unpaid",
	},
  "metaData": {
      "source": "API",
      "entity": "Payment"
  },
  "error": null
}

Get VA Availability

To check the availability of virtual accounts (VA), include the following parameters in your request:

curl --location '{{url}}/v2/payments/gs/payment-link/bank?referenceId=0876743bdbae48b8a3e7cc9fb116f867&pin=1111' \
--header 'publicAccessToken: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIzNDciLCJjb2xydXIpOOiIjMzMzMzMzIiwicm9sZSI6WyJVU0VSIl0sIm5hbWUiOiJQVCBKYXZhcyBKYXlhIEphdmEiLCJpc3MiOiJQVCBKYXZhcyBKYXlhIEphdmEiLCJleHAiOjE3MDkwMjM5OTIsImlhdCI6MTcwOTAyMzY5MiwianRpIjoiN2NmZjcyZDgtMWZmNy00NTA5LTk2MTYtODZkNjNkNjhhNmM5IiwidHMiOjE3MDkwMjM2OTIzNDR9.wUuqnlrz4dWaenrAzMSvTdSMEFiGuE_JjFG_mTrc9Cw'

Ensure that you include these parameters in your API request to retrieve the availability status of virtual accounts for the specified bank code.

Upon sending the request to check VA availability, you will receive a response containing the following information:

{
    "status": 200,
    "data": {
        "virtualAccount": [
            {
                "bankName": "Bank Negara Indonesia",
                "bankShortCode": "BNI",
                "availabilityInformation": "",
                "isAvailable": true
            },
            {
                "bankName": "Bank Maybank",
                "bankShortCode": "BII",
                "availabilityInformation": "",
                "isAvailable": true
            },
            {
                "bankName": "Bank Danamon",
                "bankShortCode": "DANAMON",
                "availabilityInformation": "",
                "isAvailable": true
            },
            {
                "bankName": "BSI (Bank Syariah Indonesia)",
                "bankShortCode": "BSI",
                "availabilityInformation": "",
                "isAvailable": true
            },
            {
                "bankName": "CIMB Niaga Bank",
                "bankShortCode": "CIMB_NIAGA",
                "availabilityInformation": "",
                "isAvailable": true
            },
            {
                "bankName": "Bank Rakyat Indonesia",
                "bankShortCode": "BRI",
                "availabilityInformation": "",
                "isAvailable": true
            },
            {
                "bankName": "Bank Mandiri",
                "bankShortCode": "MANDIRI",
                "availabilityInformation": "",
                "isAvailable": true
            },
            {
                "bankName": "Bank Permata UUS",
                "bankShortCode": "PERMATA_UUS",
                "availabilityInformation": "",
                "isAvailable": true
            },
            {
                "bankName": "Bank Sahabat Sampoerna",
                "bankShortCode": "SAHABAT_SAMPOERNA",
                "availabilityInformation": "",
                "isAvailable": true
            },
            {
                "bankName": "Bank Permata",
                "bankShortCode": "PERMATA",
                "availabilityInformation": "",
                "isAvailable": true
            }
        ],
        "bankTransfer": [
            {
                "bankName": "Bank Central Asia",
                "bankShortCode": "BCA",
                "availabilityInformation": "",
                "isAvailable": true
            }
        ]
    },
    "metaData": {
        "source": "API",
        "entity": "Payment"
    },
    "error": null
}

Cancel Payment Link

To cancel a specific payment link via the Payment Link API, include the following parameter in your request:

Method : PATCH

URL : {{base-url}}/v2/payments/gs/payment-link/cancel

publicAccessToken Header -> Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIzNDciLCJjb2xvdXIiOizMzMzMzIiwicm9sZSI6WyJVU0VSIl0sIm5hbWUiOiJQVCBKYXZhcyBKYXlhIEphdmEiLCJpc3MiOiJQVCBKYXZhcyBKYXlhIEphdmEiLCJleHAiOjE3MDkwMjU1NzAsImlhdCI6MTcwOTAyNTI3MCwianRpIjoiMTkwYWE2ODUtNzA0Ni00Y2RlLWFjNjctZmU0ZWI3NTU4NjIyIiwidHMiOjE3MDkwMjUyNzAzNDl9.tZ8lAuwRorzpv72yovlj8cfby79Bcuuirjbg6YBte0s
{
    "referenceId" : "iqipaymentlinktest562123" (REQUIRED)
}

curl --location --request PATCH '{{url}}/v2/payments/gs/payment-link/cancel' \
--header 'publicAccessToken: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIzNDciLCJjb2xvdXIiOiIjMzMzMzMzIiwicm9sZSI6WyJVU0VSIl0sIm5hbWUiOiJQVCBKYXZhcyBKYXlhIEphdmEiLCJpc3MiOiJQVCBKYXZhcyBKYXlhIEphdmEiLCJleHAiOjE3MDkwMjYwMTUsImlhdCI6MTcwOTAyNTcxNSwianRpIjoiZWRjN2FiYzgtMWRlZS00Y2Y0LTk1YWItNDNjOTU3MTYyZTMyIiwidHMiOjE3MDkwMjU3MTUyMTV9.AFERdbkKCvTyCUg4JgnQYp4dKDCRGY9ocw9RJV18qaI' \
--header 'Content-Type: application/json' \
--data '{
    "referenceId" : "28641922ff2d43b0a5cd08793cf9cbf2" (REQUIRED)
}'

Response :
{
    "status": 200,
    "data": {
        "message": "Successfully cancelled payment link"
    },
    "metaData": {
        "source": "API",
        "entity": "Payment"
    },
    "error": null
}

Upon sending the request to cancel a payment link, you will receive a response confirming the cancellation:

Check Payment Link Status

To check the status of a specific payment link via the Payment Link API, include the following parameter in your request:

curl --location '{{url}}/v2/payments/gs/payment-link/status' \
--header 'publicAccessToken: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIzNDciLCJjb2xvdXIiOiIjMzMzMzMzIiwicm9sZSI6WyJVU0VSIl0sIm5hbWUiOiJQVCBKYXZhcyBKYXlhIEphdmEiLCJpc3MiOiJQVCBKYXZhcyBKYXlhIEphdmEiLCJleHAiOjE3MDkwMjYwMTUsImlhdCI6MTcwOTAyNTcxNSwianRpIjoiZWRjN2FiYzgtMWRlZS00Y2Y0LTk1YWItNDNjOTU3MTYyZTMyIiwidHMiOjE3MDkwMjU3MTUyMTV9.AFERdbkKCvTyCUg4JgnQYp4dKDCRGY9ocw9RJV18qaI' \
--header 'Content-Type: application/json' \
--data '{
    "referenceId": "28641922ff2d43b0a5cd08793cf9cbf2",
    "pin":"1111"
}'

Ensure that you include this parameter in your API request to retrieve the current status of the specified payment link.

Method : PATCH

URL : {{base-url}}/v2/payments/gs/payment-link/cancel

Request :
publicAccessToken Header -> Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIzNDciLCJjb2xvdXIiOiIjMzMzMzMzIiwicm9sZSI6WyJVU0VSIl0sIm5hbWUiOiJQVCBKYXZhcyBKYXlhIEphdmEiLCJpc3MiOiJQVCBKYXZhcyBKYXlhIEphdmEiLCJleHAiOjE3MDkwMjU1NzAsImlhdCI6MTcwOTAyNTI3MCwianRpIjoiMTkwYWE2ODUtNzA0Ni00Y2RlLWFjNjctZmU0ZWI3NTU4NjIyIiwidHMiOjE3MDkwMjUyNzAzNDl9.tZ8lAuwRorzpv72yovlj8cfby79Bcuuirjbg6YBte0s
Body :
json
{
    "referenceId" : "iqipaymentlinktest562123" (REQUIRED)
}

Upon sending the request to check the status of a payment link, you will receive a response containing the following information:

{
    "status": 200,
    "data": {
        "message": "Successfully cancelled payment link"
    },
    "metaData": {
        "source": "API",
        "entity": "Payment"
    },
    "error": null
}

Use this response to obtain real-time updates on the status of the specified payment link, enabling effective monitoring and management of payment transactions.

📘
Testing callback in sandbox
Callbacks are sent when there are changes in payment link 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.

Create Payment Link via API

🚧
Prepare your account first

1. Generate public access token

2. Generate Payment Link

Get VA Availability

Cancel Payment Link

Check Payment Link Status

📘
Testing callback in sandbox

🚧Prepare your account first

1. Generate public access token

2. Generate Payment Link

Get VA Availability

Cancel Payment Link

Check Payment Link Status

📘Testing callback in sandbox

🚧
Prepare your account first

📘
Testing callback in sandbox