Onboard a Counterparty to an Additional Bank Partner

PATCH /v1/counter-parties//onboard — Register an existing counterparty with an additional bank partner. Requires com.diameterpay.api/counter-parties.write scope.

After a counterparty is created, you can register them with additional bank partners using this endpoint. This is necessary when a wire transfer must be routed through a bank partner the counterparty has not yet been onboarded to. Once onboarding completes successfully, the new bank partner will appear in the counterparty’s bankPartners array with an ACTIVE status.

​

Endpoint

PATCH /v1/counter-parties/{id}/onboard

Required scope: com.diameterpay.api/counter-parties.write

​

Request Headers

Authorization · string · required

Bearer token obtained from your OAuth2 token endpoint. Format: Bearer {access_token}

x-idempotency-key · string · required

A UUID v4 string that uniquely identifies this request. Replaying the same key within the idempotency window returns the original response without triggering a duplicate onboarding attempt.

​

Path Parameters

id · string · required

The UUID of the counterparty to onboard with an additional bank partner.

​

Request Body

bankPartner · string · required

The bank partner to onboard this counterparty with. Must be one of:

• PORTAGE
• SLOVAK_SAVINGS_BANK

The specified bank partner must not already be present in the counterparty’s bankPartners array.

​

Response

Returns HTTP 200 OK with the updated CounterPartyOutput object, reflecting the newly added bank partner entry in bankPartners.

id · string

UUID uniquely identifying the counterparty record.

type · string

The counterparty type: ORGANIZATION or INDIVIDUAL.

endUserId · string

UUID of the end user this counterparty belongs to.

wireInformation · object

The wire transfer details for this counterparty.

bankPartners · array

Updated list of bank partner onboarding records, now including the newly registered bank partner.

Show bankPartners item fields

bankPartner · string

The bank partner identifier: PORTAGE or SLOVAK_SAVINGS_BANK.

status · string

Current onboarding status with this bank partner:

• ACTIVE — onboarded and ready to receive payments
• BLOCKED — onboarding blocked; contact support

createdAt · string

ISO 8601 timestamp of when the counterparty was created.

updatedAt · string

ISO 8601 timestamp of the most recent update, reflecting the new onboarding.

​

Example

cURL

curl --request PATCH \
  --url https://api.diameterpay.com/v1/counter-parties/a1b2c3d4-e5f6-7890-abcd-ef1234567890/onboard \
  --header "Authorization: Bearer {access_token}" \
  --header "x-idempotency-key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  --header "Content-Type: application/json" \
  --data '{
    "bankPartner": "PORTAGE"
  }'

​

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "INDIVIDUAL",
  "endUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "firstName": "Jane",
  "lastName": "Doe",
  "wireInformation": {
    "bankName": "City Bank International",
    "accountNumber": "987654321",
    "routingNumberType": "BIC",
    "routingNumber": "CITIUS33XXX",
    "address": {
      "addressType": "HOME",
      "country": "US",
      "postalCode": "94105",
      "townName": "San Francisco",
      "streetName": "Market Street",
      "buildingNumber": "101",
      "countrySubdivision": "CA"
    }
  },
  "bankPartners": [
    {
      "bankPartner": "SLOVAK_SAVINGS_BANK",
      "status": "ACTIVE"
    },
    {
      "bankPartner": "PORTAGE",
      "status": "ACTIVE"
    }
  ],
  "createdAt": "2024-06-01T12:00:00.000Z",
  "updatedAt": "2024-06-02T09:30:00.000Z"
}