POST/counterparty/{userId}/counterparties/{counterpartyId}/instrument

Create Payment Instrument (Cross Border)

Creates a cross-border payment instrument for a counterparty. Supports multiple transfer types: GBP Wire, SEPA (EUR), SGD Domestic, AED Domestic, ARS Domestic, AUD Domestic, BRL Domestic, CAD Domestic, CAD Wire, CLP Domestic, COP Domestic, DKK Domestic, EUR Wire, GBP Faster Payments, HKD Domestic, IDR Domestic, JPY Domestic, KRW Domestic, MXN Domestic (CLABE), MYR Domestic, PEN Domestic, THB Domestic, VND Domestic.

Path variables

Field	Type	Required	Possible values	Description
`userId`	string	Required	—	Unique ID of the user. The user must be active.
`counterpartyId`	string	Required	—	Unique counterparty ID.

Headers

Field	Type	Required	Possible values	Description
`session-token`	string	Required	—	SessionToken obtained from the Create GMA Session endpoint. All secured endpoints require this header.

Request body

Field	Type	Required	Possible values	Description
`Currency`	string	Required	GBP \| EUR \| SGD \| AED \| ARS \| AUD \| BRL \| CAD \| CLP \| COP \| DKK \| JPY \| MXN \| HKD \| IDR \| KRW \| MYR \| PEN \| THB \| VND \| ZAR	Target currency for the cross-border payment.
`TransferType`	string	Required	CROSS_BORDER_AED_DOMESTIC \| CROSS_BORDER_AED_WIRE \| CROSS_BORDER_ARS_DOMESTIC \| CROSS_BORDER_BRL_DOMESTIC \| CROSS_BORDER_CAD_DOMESTIC \| CROSS_BORDER_CAD_WIRE \| CROSS_BORDER_SEPA \| CROSS_BORDER_EUR_WIRE \| CROSS_BORDER_FASTER_PAYMENTS \| CROSS_BORDER_GBP_WIRE \| CROSS_BORDER_HKD_DOMESTIC \| CROSS_BORDER_HKD_WIRE \| CROSS_BORDER_JPY_DOMESTIC \| CROSS_BORDER_JPY_WIRE \| CROSS_BORDER_CLABE \| CROSS_BORDER_MXN_WIRE \| CROSS_BORDER_SGD_DOMESTIC \| CROSS_BORDER_SGD_WIRE \| CROSS_BORDER_ZAR_DOMESTIC \| CROSS_BORDER_ZAR_WIRE \| CROSS_BORDER_CLP_DOMESTIC \| CROSS_BORDER_COP_DOMESTIC \| CROSS_BORDER_DKK_DOMESTIC \| CROSS_BORDER_IDR_DOMESTIC \| CROSS_BORDER_PEN_DOMESTIC \| CROSS_BORDER_AUD_DOMESTIC \| CROSS_BORDER_MYR_DOMESTIC \| CROSS_BORDER_KRW_DOMESTIC \| CROSS_BORDER_THB_DOMESTIC \| CROSS_BORDER_VND_DOMESTIC	Cross-border transfer type.
`CustomValues`	object	Optional	{ Nickname, Iban, SwiftBic, BankName, BankCountry, AccountNumber, RoutingCode, IdentityType, IdentityNumber, IdentityExpirationDate, PhoneNumber, BranchNumber, AccountType, TaxId, CBU, OriginatorIdentityType, OriginatorIdentityNumber, SourceOfFunds }	Bank and beneficiary details of the instrument. The applicable sub-fields depend on the selected TransferType — see the hint below the table.
`CustomValues.Nickname`	string	Optional	—	Display name for the instrument. Applies to every cross-border transfer type.
`CustomValues.Iban`	string	Optional	—	IBAN of the beneficiary account. Used by SEPA, EUR/GBP wire and AED transfer types.
`CustomValues.SwiftBic`	string	Optional	—	SWIFT/BIC code of the beneficiary bank. Used by SEPA, SGD and wire transfer types.
`CustomValues.BankName`	string	Optional	—	Name of the beneficiary bank.
`CustomValues.BankCountry`	string	Optional	e.g. US \| GB \| DE	ISO 3166-1 alpha-2 country code of the beneficiary bank.
`CustomValues.AccountNumber`	string	Optional	—	Beneficiary account number. Used by most local/domestic transfer types.
`CustomValues.RoutingCode`	string	Optional	—	Local routing code of the beneficiary bank. Used by SGD Domestic.
`CustomValues.IdentityType`	string	Optional	PASSPORT \| DRIVING_LICENSE \| NATIONAL_ID	Type of the beneficiary identity document. Used by AED, BRL, CLP, COP, PEN and THB transfer types.
`CustomValues.IdentityNumber`	string	Optional	—	Identity document number matching IdentityType.
`CustomValues.IdentityExpirationDate`	string	Optional	YYYY-MM-DD	Expiry date of the identity document in YYYY-MM-DD format. Used by AED transfer types. Must have at least 6 months remaining before expiration.
`CustomValues.PhoneNumber`	string	Optional	—	Beneficiary phone number in E.164 format. Used by AED, COP and KRW transfer types.
`CustomValues.BranchNumber`	string	Optional	—	Branch number of the beneficiary bank. Used by BRL, DKK and AUD transfer types.
`CustomValues.AccountType`	string	Optional	Saving \| Checking	Type of the beneficiary bank account. Used by BRL, CLP, COP and PEN transfer types.
`CustomValues.TaxId`	string	Optional	—	Beneficiary tax identification number. Used by CLP, COP and PEN transfer types.
`CustomValues.CBU`	string	Optional	—	Clave Bancaria Uniforme of the beneficiary account. Used by ARS Domestic.
`CustomValues.OriginatorIdentityType`	string	Optional	PASSPORT \| NATIONAL_ID \| DRIVING_LICENSE	Type of the originator identity document. Used by IDR Domestic.
`CustomValues.OriginatorIdentityNumber`	string	Optional	—	Originator identity document number. Used by IDR and MYR transfer types.
`CustomValues.SourceOfFunds`	string	Optional	CASH \| BUSINESS \| GIFT \| SALARY \| LOTTERY \| SAVINGS \| OTHER	Source of the funds being sent. Used by MYR Domestic.

Example request

{
  "Currency": "GBP",
  "TransferType": "CROSS_BORDER_GBP_WIRE",
  "CustomValues": {
    "Nickname": "UK Wire Account",
    "Iban": "GB29NWBK60161331926819",
    "SwiftBic": "NWBKGB2L",
    "BankName": "National Westminster Bank",
    "BankCountry": "GB"
  }
}

{
  "Currency": "GBP",
  "TransferType": "CROSS_BORDER_GBP_WIRE",
  "CustomValues": {
    "Nickname": "UK Wire Account",
    "Iban": "GB29NWBK60161331926819",
    "SwiftBic": "NWBKGB2L",
    "BankName": "National Westminster Bank",
    "BankCountry": "GB"
  }
}

ℹ Note

CustomValues fields vary by TransferType. Nickname, Iban, SwiftBic, BankName and BankCountry are the common fields. Retrieve the exact required fields for the corresponding transfer type from the Get Required Fields for Instruments endpoint.

SEPA — Iban, SwiftBic
SGD — AccountNumber, SwiftBic, RoutingCode
AED — Iban, IdentityType, IdentityNumber, IdentityExpirationDate, PhoneNumber
BRL — AccountNumber, BranchNumber, IdentityType, IdentityNumber, AccountType
ARS — CBU
COP — AccountNumber, AccountType, TaxId, PhoneNumber, IdentityType, IdentityNumber
CLP — AccountNumber, AccountType, TaxId, IdentityType, IdentityNumber
DKK — AccountNumber, BranchNumber
IDR — AccountNumber, OriginatorIdentityType, OriginatorIdentityNumber
PEN — AccountNumber, AccountType, TaxId, IdentityType, IdentityNumber
AUD — AccountNumber, BranchNumber
MYR — AccountNumber, OriginatorIdentityNumber, SourceOfFunds
KRW — AccountNumber, PhoneNumber
THB — AccountNumber, IdentityType, IdentityNumber
VND — AccountNumber

Response

Field	Type	Possible values	Description
`ResponseCode`	integer	200 \| 201 \| 204 \| 301 \| 400 \| 401 \| 403 \| 404 \| 410 \| 422 \| 500 \| 503	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 cross-border payment instrument.

Example response

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": "-8134735344136966182"
}

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": "-8134735344136966182"
}

CustomValues fields vary significantly by TransferType. Use Get Required Fields to retrieve the exact field schema for each transfer type.

Requires `session-token: {SessionToken}` from Create GMA Session. Use the same client IP as authentication.