These docs are for v4.0.2. Click to read the latest docs for v4.3.0.

Beneficiary Registration API

By registering beneficiary merchant through Payout API, it allows merchant to simply pass token (BeneficiaryID) without the need to fill in other beneficiary information in the subsequent payout request. Please note that while registering beneficiary to Payout API, we also verify voidability of beneficiary information through payout provider or bank.

👍

HTTPS POST / Server-to-Server

Beneficiary registration requests and responses are encrypted using JWT with HS256 algorithm (HMAC with SHA-256) using Merchant’s Secret Key.

Merchants must know how to prepare requests and process responses using JWT Token.

https://sandbox-pgw.2c2p.com/payouts/api/v1.1/payout/beneficiary/register 
https://pgw.2c2p.com/payouts/api/v1.1/payout/beneficiary/register 
https://pgw.2c2p.com/payouts/api/v1.1/payout/beneficiary/register 

📘

API Parameter

Beneficiary Registration Parameter
Beneficiary Registration Response / Notification Parameter

Prepare Request

  1. Prepare payload data.
  2. Encrypt payload data with JWT - HS256 algorithm using merchant secret key.
{
  "version": "1.1",
  "merchantID": "702702000000001",
  "requestID": "557f2de7-db81-40e9-9066-2821e7100a32",
  "IdCard": "",
  "accountName": "NGUYEN van a",  
  "bankCode": "AGRIBANK",
  "emailAddress": "[email protected]",
  "mobileNo": "",
  "companyId": "",
  "beneficiaryType": "",
  "beneficiaryTypeValue": "",
  "notificationUrl": "https://myweb.com/callback/notification" 
}

{
	"payload": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2ZXJzaW9uIjoiMS4xIiwibWVyY2hhbnRJRCI6IjcwMjcwMjAwMDAwMDAwMSIsInJlcXVlc3RJRCI6IjU1N2YyZGU3LWRiODEtNDBlOS05MDY2LTI4MjFlNzEwMGEzMiIsIklkQ2FyZCI6IiIsImFjY291bnROYW1lIjoiTkdVWUVOIHZhbiBhIiwiYmFua0NvZGUiOiJBR1JJQkFOSyIsImVtYWlsQWRkcmVzcyI6InByYXNvbmdAMmMycC5jb20iLCJtb2JpbGVObyI6IiIsImNvbXBhbnlJZCI6IiIsImJlbmVmaWNpYXJ5VHlwZSI6IiIsImJlbmVmaWNpYXJ5VHlwZVZhbHVlIjoiIiwibm90aWZpY2F0aW9uVXJsIjoiaHR0cHM6Ly9teXdlYi5jb20vY2FsbGJhY2svbm90aWZpY2F0aW9uIn0.aK78omuFmmJJuc6t9FXmFgpEtaL1YdZw6d3EF6837pg"
}
  1. Send request to beneficiary registration API.
curl --location --request POST 'https://sandbox-pgw.2c2p.com/payouts/api/v1.1/payout/beneficiary/register' \
--header 'Content-Type: application/json' \
--data-raw '{
	"payload": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2ZXJzaW9uIjoiMS4xIiwibWVyY2hhbnRJRCI6IjcwMjcwMjAwMDAwMDAwMSIsInJlcXVlc3RJRCI6IjU1N2YyZGU3LWRiODEtNDBlOS05MDY2LTI4MjFlNzEwMGEzMiIsIklkQ2FyZCI6IiIsImFjY291bnROYW1lIjoiTkdVWUVOIHZhbiBhIiwiYmFua0NvZGUiOiJBR1JJQkFOSyIsImVtYWlsQWRkcmVzcyI6InByYXNvbmdAMmMycC5jb20iLCJtb2JpbGVObyI6IiIsImNvbXBhbnlJZCI6IiIsImJlbmVmaWNpYXJ5VHlwZSI6IiIsImJlbmVmaWNpYXJ5VHlwZVZhbHVlIjoiIiwibm90aWZpY2F0aW9uVXJsIjoiaHR0cHM6Ly9teXdlYi5jb20vY2FsbGJhY2svbm90aWZpY2F0aW9uIn0.aK78omuFmmJJuc6t9FXmFgpEtaL1YdZw6d3EF6837pg"
}'

Receive Response

  1. Receiving encrypted beneficiary data immediately.
  2. Decrypt payload data with JWT - HS256 algorithm using merchant secret key.
{
    "version": "1.1",
    "requestId": "591e6e59-dd19-4911-ae77-cf0043f4070b",
    "beneficiaryId": "payout_Prod_BFWW4eWRndEUmud88AQ_QHCw",
    "accountName": "NGUYEN Van A",
    "emailAddress": "[email protected]",
    "mobileNo": "",
    "bankCode": "AGRIBANK",
    "merchantId": "702702000000001",
    "idCard": "",
    "comanyId": null,
    "beneficiaryType": "",
    "beneficiaryTypeValue": "",
    "notificationUrl": "https://merchantweb.com/notification/callback",
    "respCode": "8180",
    "respDesc": "Success – Payout beneficiary registration success",
    "remarks": null

}
{
	"payload": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2ZXJzaW9uIjoiMS4xIiwicmVxdWVzdElkIjoiNTkxZTZlNTktZGQxOS00OTExLWFlNzctY2YwMDQzZjQwNzBiIiwiYmVuZWZpY2lhcnlJZCI6InBheW91dF9Qcm9kX0JGV1c0ZVdSbmRFVW11ZDg4QVFfUUhDdyIsImFjY291bnROYW1lIjoiTkdVWUVOIFZhbiBBIiwiZW1haWxBZGRyZXNzIjoibWVyY2hhbnRAbWVyY2hhbnR3ZWIuY29tIiwibW9iaWxlTm8iOiIiLCJiYW5rQ29kZSI6IkFHUklCQU5LIiwibWVyY2hhbnRJZCI6IjcwMjcwMjAwMDAwMDAwMSIsImlkQ2FyZCI6IiIsImNvbWFueUlkIjpudWxsLCJiZW5lZmljaWFyeVR5cGUiOiIiLCJiZW5lZmljaWFyeVR5cGVWYWx1ZSI6IiIsIm5vdGlmaWNhdGlvblVybCI6Imh0dHBzOi8vbWVyY2hhbnR3ZWIuY29tL25vdGlmaWNhdGlvbi9jYWxsYmFjayIsInJlc3BDb2RlIjoiODE4MCIsInJlc3BEZXNjIjoiU3VjY2VzcyDigJMgUGF5b3V0IGJlbmVmaWNpYXJ5IHJlZ2lzdHJhdGlvbiBzdWNjZXNzIiwicmVtYXJrcyI6bnVsbH0.MOuBX0OeqjyDbzrR-As6-PtwP2CfXmZCiLpRIUgYBsE"
}