Create a New Counterparty Payment Recipient

POST /v1/counter-parties — Register a new payment recipient for an end user. Pre-creating counterparties avoids delays at wire initiation time.

Creating a counterparty registers a payment recipient — either an individual or an organization — against an end user’s profile. By pre-creating counterparties ahead of wire initiation, you eliminate validation delays at the point of payment and ensure bank-partner onboarding is completed in advance. Each counterparty is scoped to a single end user and can be onboarded to one or more supported bank partners.

​

Endpoint

POST /v1/counter-parties

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 creating a duplicate.

​

Request Body

type · string · required

The counterparty classification. Must be one of:

• ORGANIZATION — a business or legal entity
• INDIVIDUAL — a natural person

endUserId · string · required

UUID of the end user who owns this counterparty.

bankPartner · string · required

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

• PORTAGE
• SLOVAK_SAVINGS_BANK

fullName · string

Full legal name of the counterparty. Required when type is ORGANIZATION.

firstName · string

First name of the counterparty. Required when type is INDIVIDUAL.

lastName · string

Last name of the counterparty. Required when type is INDIVIDUAL.

middleName · string

Middle name of the counterparty. Optional — applicable only when type is INDIVIDUAL.

wireInformation · object · required

Bank account and routing details used to execute wire transfers to this counterparty.

Show wireInformation fields

bankName · string · required

The name of the counterparty’s receiving bank.

accountNumber · string · required

The counterparty’s bank account number.

routingNumberType · string · required

The type of routing identifier. Must be one of:

• ABA — American Bankers Association routing number (domestic)
• BIC — Business Identifier Code (international / SWIFT)

routingNumber · string · required

The ABA routing number or BIC/SWIFT code for the receiving bank.

address · object · required

The counterparty’s postal address associated with their bank account.

Show address fields

addressType · string · required

Standardized address type code. Must be one of:

• ADDR — postal address
• PBOX — PO box
• HOME — residential address
• BIZZ — business address
• MLTO — mailing-to address
• DLVY — delivery address

country · string · required

ISO 3166-1 alpha-2 country code (e.g. US, GB, DE).

postalCode · string · required

Postal or ZIP code for the address.

townName · string · required

City or town name.

streetName · string · required

Street name (excluding building number).

buildingNumber · string

Building or house number. Optional.

countrySubdivision · string

State, province, or region code. Optional (e.g. CA, NY).

​

Response

Returns HTTP 201 Created with a CounterPartyOutput object on success.

id · string

UUID uniquely identifying this 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 provided at creation, including bankName, accountNumber, routingNumberType, routingNumber, and address.

bankPartners · array

List of bank partner onboarding records for this counterparty.

Show bankPartners item fields

bankPartner · string

The bank partner identifier: PORTAGE or SLOVAK_SAVINGS_BANK.

status · string

Current onboarding status with the 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 to the counterparty record.

​

Examples

​

Create an Organization Counterparty

cURL

curl --request POST \
  --url https://api.diameterpay.com/v1/counter-parties \
  --header "Authorization: Bearer {access_token}" \
  --header "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "ORGANIZATION",
    "endUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bankPartner": "PORTAGE",
    "fullName": "Acme Corp LLC",
    "wireInformation": {
      "bankName": "First National Bank",
      "accountNumber": "123456789",
      "routingNumberType": "ABA",
      "routingNumber": "021000021",
      "address": {
        "addressType": "BIZZ",
        "country": "US",
        "postalCode": "10001",
        "townName": "New York",
        "streetName": "5th Avenue",
        "buildingNumber": "350",
        "countrySubdivision": "NY"
      }
    }
  }'

​

Create an Individual Counterparty

cURL

curl --request POST \
  --url https://api.diameterpay.com/v1/counter-parties \
  --header "Authorization: Bearer {access_token}" \
  --header "x-idempotency-key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "INDIVIDUAL",
    "endUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bankPartner": "SLOVAK_SAVINGS_BANK",
    "firstName": "Jane",
    "middleName": "Marie",
    "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"
      }
    }
  }'

​

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "INDIVIDUAL",
  "endUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "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"
    }
  ],
  "createdAt": "2024-06-01T12:00:00.000Z",
  "updatedAt": "2024-06-01T12:00:00.000Z"
}