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, BRL Domestic, CAD Domestic, CAD Wire, EUR Wire, GBP Faster Payments, JPY Domestic, MXN Domestic (CLABE).

Path variables

Field	Type	Required	Possible values	Description
`userId`	string	Required	—	Unique user ID.
`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 \| BRL \| CAD \| JPY \| MXN \| HKD \| 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_WIREY \| 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 transfer type.
`CustomValues`	object	Optional	{ Nickname, Iban, SwiftBic, BankName, BankCountry, AccountNumber, RoutingCode, IdentityType, IdentityNumber, IdentityExpirationDate, PhoneNumber, BranchNumber, AccountType, CBU }	Cross-border instrument fields vary by TransferType. Common fields: Nickname, Iban, SwiftBic, BankName, BankCountry. SEPA: Iban + SwiftBic. SGD: AccountNumber + SwiftBic + RoutingCode. AED: Iban + IdentityType + IdentityNumber + IdentityExpirationDate + PhoneNumber. BRL: AccountNumber + BranchNumber + IdentityType + IdentityNumber + AccountType. ARS: CBU. Retrieve the required fields for the corresponding transfer type from the Get Required Fields for Instruments endpoint.

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"
  }
}

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.