Create a Counterparty
Register a payment destination with an external account.
What is a Counterparty?
A counterparty represents a person or organization you send money to or receive money from. Each counterparty has one or more external accounts (their bank accounts) identified by IBAN, BBAN, or account number.
Counterparties must be created before initiating any credit transfers or direct debits.
Create a Counterparty
The request below creates a counterparty with a single external account. The returned external account ID (accounts[0].id) is automatically saved and will be used as the payment destination in the next step.
/payments/v2/counterpartiesCreate a counterparty with an external account. Returns the counterparty and external account IDs.
curl -X POST 'https://api.atlar.com/payments/v2/counterparties' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"legalName": "Example Company GmbH",
"alias": "Customer #1234",
"partyType": "INDIVIDUAL",
"email": "john.smith@example.com",
"address": {
"country": "DE",
"city": "Berlin",
"postalCode": "10115",
"streetName": "Example Strasse",
"streetNumber": "47"
},
"nationalIdentifier": {
"type": "CIVIC",
"market": "DE",
"number": "2012121212"
},
"metadata": { "segment": "trial" },
"accounts": [
{
"market": "DE",
"identifiers": [
{
"type": "IBAN",
"market": "DE",
"number": "DE64500105173198833324"
}
]
}
]
}'Dashboard: Counterparties
View and manage all counterparties. Click into any counterparty to see its external accounts, mandates, and metadata.
Key fields explained
| Field | Description |
|---|---|
legalName | Full legal name of the counterparty (required) |
alias | Friendly display name for internal reference |
partyType | INDIVIDUAL or ORGANIZATION |
accounts[].identifiers | Bank account identifiers (IBAN, BBAN, or account number) |
accounts[].market | ISO country code for the account (e.g. "DE") |
metadata | Arbitrary key-value pairs for your own tagging |
externalId | Optional: your own ID (regex: ^[a-zA-Z0-9._\-+=]{1,64}$) |
Use fictitious data for testing
In your sandbox, always use fictitious names, addresses, and test IBANs. The example above uses Example Company GmbH and a generated IBAN — no real personal data is needed.
External IDs
Use the externalId field to link counterparties to your own systems. You can then look up the counterparty with GET /payments/v2/counterparties/external:YOUR_ID.