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

Create Payment Instrument (USD - International Wire)

Creates a USD international wire payment instrument for a counterparty.

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	USD	Payment currency.
`TransferType`	string	Required	INTERNATIONAL_WIRE	Transfer type for this instrument.
`CustomValues.Nickname`	string	Required	—	Display name for the instrument.
`CustomValues.AccountNumber`	string	Required	—	Beneficiary bank account number.
`CustomValues.SwiftBic`	string	Required	—	SWIFT/BIC code of the beneficiary bank.
`CustomValues.AccountType`	string	Required	Saving \| Checking	Type of the beneficiary bank account.
`CustomValues.BankName`	string	Required	—	Name of the beneficiary bank.
`CustomValues.BankAddress`	string	Required	—	Street address of the beneficiary bank.
`CustomValues.BankCity`	string	Required	—	City of the beneficiary bank.
`CustomValues.BankState`	string	Required	—	State or region of the beneficiary bank.
`CustomValues.BankPostalCode`	string	Required	—	Postal code of the beneficiary bank.
`CustomValues.BankCountry`	string	Required	e.g. US \| GB \| DE	ISO 3166-1 alpha-2 country code of the beneficiary bank.

Example request

{
  "Currency": "USD",
  "TransferType": "INTERNATIONAL_WIRE",
  "CustomValues": {
    "Nickname": "International Transfer Account",
    "AccountNumber": "****6818",
    "SwiftBic": "CHASUS33",
    "AccountType": "Checking",
    "BankName": "Wells Fargo Bank",
    "BankAddress": "420 Montgomery Street",
    "BankCity": "San Francisco",
    "BankState": "CA",
    "BankPostalCode": "94104",
    "BankCountry": "MX"
  }
}

{
  "Currency": "USD",
  "TransferType": "INTERNATIONAL_WIRE",
  "CustomValues": {
    "Nickname": "International Transfer Account",
    "AccountNumber": "****6818",
    "SwiftBic": "CHASUS33",
    "AccountType": "Checking",
    "BankName": "Wells Fargo Bank",
    "BankAddress": "420 Montgomery Street",
    "BankCity": "San Francisco",
    "BankState": "CA",
    "BankPostalCode": "94104",
    "BankCountry": "MX"
  }
}

ℹ Note

CustomValues for TransferType INTERNATIONAL_WIRE: Nickname, AccountNumber, SwiftBic, AccountType, BankName, BankAddress, BankCity, BankState, BankPostalCode, BankCountry. Retrieve the exact required fields from the Get Required Fields for Instruments endpoint.

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 payment instrument.

Example response

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": "3696220876965326813"
}

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": "3696220876965326813"
}

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