how to add a beneficiary in payment transaction

You should create beneficiary before making payment transaction. The beneficiary is an individual or organization of specific currency and payment network. This article describes in detail how to add a beneficiary.

1. Use /v1/banking/beneficiaries/required-details endpoint to query the information needed to add a beneficiary. For example, GET /v1/banking/beneficiaries/required-details?currency=USD&beneficiary_type=personal you will get the filelds used to create a USD personal beneficiary.

   {
   	"code": 0,
   	"msg": "Ok",
   	"data": [{
   		"currency": "USD",
   		"beneficiary_type": "personal",
   		"payment_type": "local"
   		"fields": [{
   			"field": "account_name",
   			"required": true,
   			"regex": "",
   			"data_type": "text"
   		}, {
   			"field": "first_name",
   			"required": true,
   			"regex": "",
   			"data_type": "text"
   		}, {
   			"field": "last_name",
   			"required": true,
   			"regex": "",
   			"data_type": "text"
   		}, {
   			"field": "mobile",
   			"required": true,
   			"regex": "",
   			"data_type": "phone"
   		}, {
   			"field": "region_country",
   			"required": true,
   			"regex": "",
   			"data_type": "country"
   		}, {
   			"field": "aba_routing_code",
   			"required": true,
   			"regex": "^[\\d ]{6,13}$",
   			"data_type": "number"
   		}, {
   			"field": "account_no",
   			"required": true,
   			"regex": "^[\\d ]+$",
   			"data_type": "number"
   		}, {
   			"field": "address_country",
   			"required": true,
   			"regex": "",
   			"data_type": "country"
   		}, {
   			"field": "address_state",
   			"required": true,
   			"regex": "",
   			"data_type": "text"
   		}, {
   			"field": "address_city",
   			"required": true,
   			"regex": "",
   			"data_type": "text"
   		}, {
   			"field": "address_address1",
   			"required": true,
   			"regex": "",
   			"data_type": "text"
   		}, {
   			"field": "address_address2",
   			"required": false,
   			"regex": "",
   			"data_type": "text"
   		}, {
   			"field": "address_postcode",
   			"required": false,
   			"regex": "^[\\d-A-Za-z]+$",
   			"data_type": "text"
   		}],
   	}, {
   		"currency": "USD",
   		"beneficiary_type": "personal",
   		"payment_type": "swift"
   		"fields": [{
   			"field": "account_name",
   			"required": true,
   			"regex": "",
   			"data_type": "text"
   		}, {
   			"field": "first_name",
   			"required": true,
   			"regex": "",
   			"data_type": "text"
   		}, {
   			"field": "last_name",
   			"required": true,
   			"regex": "",
   			"data_type": "text"
   		}, {
   			"field": "mobile",
   			"required": true,
   			"regex": "",
   			"data_type": "phone"
   		}, {
   			"field": "region_country",
   			"required": true,
   			"regex": "",
   			"data_type": "country"
   		}, {
   			"field": "swift_code",
   			"required": true,
   			"regex": "^[a-zA-Z0-9 ]{6,15}$",
   			"data_type": "text"
   		}, {
   			"field": "iban_no",
   			"required": true,
   			"regex": "^[a-zA-Z0-9 ]+$",
   			"data_type": "text"
   		}, {
   			"field": "address_country",
   			"required": true,
   			"regex": "",
   			"data_type": "country"
   		}, {
   			"field": "address_state",
   			"required": true,
   			"regex": "",
   			"data_type": "text"
   		}, {
   			"field": "address_city",
   			"required": true,
   			"regex": "",
   			"data_type": "text"
   		}, {
   			"field": "address_address1",
   			"required": true,
   			"regex": "",
   			"data_type": "text"
   		}, {
   			"field": "address_address2",
   			"required": false,
   			"regex": "",
   			"data_type": "text"
   		}, {
   			"field": "address_postcode",
   			"required": false,
   			"regex": "^[\\d-A-Za-z]+$",
   			"data_type": "text"
   		}],
   	}]
   }
   

   In this response, payment_type represents the payment method. fields contains the information required by the specific payment method. Its internal field field indicates the field name, required indicates whether it is required, regex indicates the rules that the value must match.

2. After got the fields, use the POST /v1/banking/beneficiaries endpoint to create a beneficiary. For a swift beneficiary, the payload should be:

   name	type	required	description
   uid	string	Y	user id, eg: 1643886388594307073
   currency	string	Y	currency code, eg: USD
   beneficiary_type	string	Y	personal or business, eg: personal
   payment_type	string	Y	payment_type response in /v1/banking/beneficiaries/required-details response. eg: swift
   account_name	string	Y	bank account name. eg. Michael Jorden
   first_name	string	Y	first name of beneficiary, eg: Jim
   last_name	string	Y	last name of beneficiary, eg:Green
   mobile	string	Y	phone number of beneficiary
   region_country	string	Y	country/region of Bank, eg: AU
   swift_code	string	Y	SWIFT code, eg: UBSWCNBJ
   iban_no	string	Y	IBAN number, eg: FI211234569876543210
   address_country	string	Y	country/region of beneficiary, ISO 3166 alpha-2 standard, eg:AU
   address_state	string	Y	state of beneficiary,eg: New South Wales
   address_city	string	Y	city of beneficiary, eg:Sydney
   address_address1	string	Y	address of beneficiary, eg:45/317-323 Pitt St Sydney NSW 2000 Australia
   address_address2	string	N	additional address of beneficiary
   address_postcode	string	N	postcode of beneficiary, eg:123456

   If every field is valid, a beneficiary will be successfully created and the beneficiary id will be returned. Then you can use this id to do payment transactions.

​