POST/v2/payment-instrument/create

Create Payment Instrument

Creates a payment instrument (bank account, wire, etc.) linked to a beneficiary.

Headers

Field	Type	Required	Possible values	Description
`Authorization`	string	Required	Bearer {SessionToken}	Session token from Get Session Token, sent as `Authorization: Bearer {SessionToken}`. Replace with the value from the `x-refresh-token` response header when present (typically within 2 minutes of expiry). Secured calls must use the same IP as the auth request.

Request body

Field	Type	Required	Possible values	Description
`fields`	object	Required	[{ "field": "FieldName", "value": "..." }]	Field values from Get Required Fields (Create Payment Instrument). JSON array: [{ "field": "FieldName", "value": "..." }].
`Additional_Info`	object	Optional	—	Optional bank details when Routing Number or SWIFT Code cannot be resolved. Include Bank_Name, Bank_Address, Bank_City, Bank_State, Bank_Postal_Code, and Bank_Country.

Example request

[
  {
    "field": "BeneficiaryId",
    "value": "{beneficiaryID}"
  },
  {
    "field": "Payment_Type",
    "value": "BUS_USD_Account.payment_cross_border_sepa"
  },
  {
    "field": "Nickname",
    "value": "EUR SEPA Beneficiary"
  …

Additional Info

Additional_Info is optional unless bank details cannot be resolved from the Routing Number or SWIFT Code. In that case, include bank details in the additional_info object.

Required fields in additional_info: • Bank_Name • Bank_Address • Bank_City • Bank_State • Bank_Postal_Code • Bank_Country

Example:

{
  "additional_info": {
    "Bank_Name": "Example Bank",
    "Bank_Address": "123 Main Street",
    "Bank_City": "New York",
    "Bank_State": "NY",
    "Bank_Postal_Code": "10001",
    "Bank_Country": "US"
  }
}

Note: Use the Get Bank Details endpoint to fetch beneficiary bank details using routing number.

Response

Field	Type	Possible values	Description
`ResponseCode`	integer	200 \| 201 \| 204 \| 400 \| 401 \| 403 \| 404 \| 410 \| 422 \| 500 \| 301 \| 503 \| 422	API result code in the response envelope. Indicates success or the error category (e.g. 200 success, 400 bad request, 401 unauthorized).
`ResponseMessage`	string	Success \| Created \| NoContent \| BadRequest \| Unauthorized \| Forbidden \| NotFound \| Gone \| UnprocessableContent \| ServerError \| ResourceMoved \| ServiceUnAvailable \| UnProcessableEntity	Human-readable label paired with ResponseCode (e.g. Success, BadRequest, Unauthorized). Use with ResponseCode to interpret the outcome.
`ResponseData`	object	Please refer to below example for response body	ID of the newly created payment instrument (use as BeneficiaryPaymentInstrumentID in payments).

Example response

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": {
    "BeneficiaryId": "4934710774492212995"
  }
}

Requires `Authorization: Bearer {SessionToken}` from Get Session Token. Refresh via `x-refresh-token` when supplied; use the same client IP as authentication.