Skip to content

Create payment contact

POST
/api/v1/organizations/{organization_id}/payment-contacts
curl --request POST \
--url https://api.elephants.inc/api/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/payment-contacts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "destination": { "account_holder_name": "example", "account_type": "individual", "address": "example", "bank": { "name": "example" }, "bank_details": { "aba_code": "example", "account_number": "example", "bank_code": "example", "bank_name": "example", "bic_code": "example", "branch_code": "example", "branch_name": "example", "bsb_code": "example", "cnaps": "example", "iban": "example", "ifsc_code": "example", "sort_code": "example", "swift_code": "example" }, "bank_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "coin_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "counterparty": { "account_reference": "example", "mark_as_own_account": true, "name": "example", "person_type": "natural", "street_address": { "address_line1": "example", "address_line2": "example", "city": "example", "country_alpha2": "example", "postal_code": "example", "state": "example", "state_code": "example" } }, "country_alpha2": "example", "currency": "example", "ele_id": "example", "is_own_account": true, "mark_as_own_account": true, "nickname": "example", "phone_country_code": "example", "phone_number": "example", "rail": "fiat", "relationship_to_sender": "example", "street_address": { "address_line1": "example", "address_line2": "example", "city": "example", "country_alpha2": "example", "postal_code": "example", "state": "example", "state_code": "example" }, "tax_id": "example" }, "name": "example", "nickname": "example", "tag": "vendor" }'

Create a payment contact, destination, and approval request atomically.

organization_id
required
string format: uuid

The organization’s ID

Payment contact fields

Media typeapplication/json
CreatePaymentContactRequestBody
object
destination
One of: discriminator: rail
FiatDestinationInput
object
account_holder_name
required
string
<= 255 characters
account_type
required
string
Allowed values: individual business
address
string
<= 255 characters
bank
DestinationBankInput
object
name
required
string
<= 255 characters
bank_details
required
DestinationBankDetailsInput
object
aba_code
string
<= 64 characters
account_number
string
<= 255 characters
bank_code
string
<= 64 characters
bank_name
required
string
<= 255 characters
bic_code
string
<= 64 characters
branch_code
string
<= 64 characters
branch_name
string
<= 255 characters
bsb_code
string
<= 64 characters
cnaps
string
<= 64 characters
iban
string
<= 255 characters
ifsc_code
string
<= 64 characters
sort_code
string
<= 64 characters
swift_code
string
<= 64 characters
bank_id
string format: uuid
coin_id
string format: uuid
counterparty
DestinationCounterpartyInput
object
account_reference
string
<= 255 characters
mark_as_own_account
boolean
name
string
<= 255 characters
person_type
string
Allowed values: natural legal
street_address
DestinationStreetAddressInput
object
address_line1
required
string
<= 255 characters
address_line2
string
<= 255 characters
city
required
string
<= 255 characters
country_alpha2
required
string
<= 16 characters
postal_code
string
<= 255 characters
state
string
<= 255 characters
state_code
string
<= 16 characters
country_alpha2
required
string
<= 16 characters
currency
required
string
<= 16 characters
ele_id

The payee’s Ele ID, with or without a leading @.

string
>= 1 characters <= 31 characters
is_own_account
boolean
mark_as_own_account
boolean
nickname
string
<= 255 characters
phone_country_code
string
<= 16 characters
phone_number
string
<= 255 characters
rail
required
string
Allowed values: fiat
relationship_to_sender
string
<= 255 characters
street_address
DestinationStreetAddressInput
object
address_line1
required
string
<= 255 characters
address_line2
string
<= 255 characters
city
required
string
<= 255 characters
country_alpha2
required
string
<= 16 characters
postal_code
string
<= 255 characters
state
string
<= 255 characters
state_code
string
<= 16 characters
tax_id
string
<= 255 characters
name
required

Name of the payment contact

string
<= 255 characters
nickname

Optional nickname for the contact

string
<= 255 characters
tag

Category for the contact

string
Allowed values: vendor own_account employee other

The created payment contact

Media typeapplication/json
PaymentContact
object
approval_request
required
One of:
PaymentContactApprovalRequest
object
id
required
string format: uuid
status
required

Approval state of the request governing this contact

string
Allowed values: pending approved rejected cancelled
destination
required
One of:
One of: discriminator: rail
FiatDestination
object
account_holder_name
required
string
account_type
required
string
Allowed values: individual business
bank
required
object
country_alpha2
required
string
name
required
string
bank_details
required
Array<object>
object
label
required
string | null
name
required
string
value
required
string
country_alpha2
required
string
currency
required
string
id
required
string format: uuid
is_own_account
required
boolean
nickname
required
string | null
rail
required
string
Allowed values: fiat
registration_failed_at
required
string | null format: date-time
registration_failure_message
required

Why the last registration attempt failed, in customer-facing copy. Null once active.

string | null
<= 500 characters
status
required

Whether the destination is registered with the payout partner. Only active destinations can be quoted or paid.

string
Allowed values: draft active
street_address
required
object
address_line1
required
string
address_line2
required
string | null
city
required
string
country_code
required
string
iso_subdivision_code
required
string | null
postal_code
required
string | null
state
required
string | null
state_code
required
string | null
event
required
One of:
OperationEvent
object
id
required

The domain event’s id

string format: uuid
stream
required

The event stream it was written to, e.g. “payment_contact_events”

string
subject_id
required

The id of the aggregate the event belongs to

string format: uuid
type
required

The event type, e.g. “payment_contact.created”

string
id
required
string format: uuid
name
required

Contact name

string
nickname
required

Optional nickname

string | null
tag
required

Contact category

string | null
Allowed values: vendor own_account employee other

Example

{
"approval_request": {
"status": "pending"
},
"destination": {
"account_type": "individual",
"rail": "fiat",
"status": "draft"
},
"tag": "vendor"
}

Invalid request parameters or body

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
"error": {
"details": "example",
"message": "example",
"request_id": "example",
"step_up": {
"delivery": "example",
"expires_at": "2026-04-15T12:00:00Z",
"id": "example",
"match_code": "example",
"methods": [
"example"
],
"step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"webauthn": {
"allow_credentials": [
{
"id": "example",
"transports": [
"example"
],
"type": "example"
}
],
"challenge": "example",
"challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"rp_id": "example",
"timeout": 1,
"user_verification": "example"
}
},
"type": "example"
}
}

Missing, invalid, or expired bearer token

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
"error": {
"details": "example",
"message": "example",
"request_id": "example",
"step_up": {
"delivery": "example",
"expires_at": "2026-04-15T12:00:00Z",
"id": "example",
"match_code": "example",
"methods": [
"example"
],
"step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"webauthn": {
"allow_credentials": [
{
"id": "example",
"transports": [
"example"
],
"type": "example"
}
],
"challenge": "example",
"challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"rp_id": "example",
"timeout": 1,
"user_verification": "example"
}
},
"type": "example"
}
}

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
"error": {
"details": "example",
"message": "example",
"request_id": "example",
"step_up": {
"delivery": "example",
"expires_at": "2026-04-15T12:00:00Z",
"id": "example",
"match_code": "example",
"methods": [
"example"
],
"step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"webauthn": {
"allow_credentials": [
{
"id": "example",
"transports": [
"example"
],
"type": "example"
}
],
"challenge": "example",
"challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"rp_id": "example",
"timeout": 1,
"user_verification": "example"
}
},
"type": "example"
}
}

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
"error": {
"details": "example",
"message": "example",
"request_id": "example",
"step_up": {
"delivery": "example",
"expires_at": "2026-04-15T12:00:00Z",
"id": "example",
"match_code": "example",
"methods": [
"example"
],
"step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"webauthn": {
"allow_credentials": [
{
"id": "example",
"transports": [
"example"
],
"type": "example"
}
],
"challenge": "example",
"challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"rp_id": "example",
"timeout": 1,
"user_verification": "example"
}
},
"type": "example"
}
}

The account already belongs to a live contact in this organization. details.existing_payment_contact_id is the one to use instead.

Media typeapplication/json
DuplicatePaymentContactError
object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string
error
required
object
details
required
object
existing_payment_contact_id
required
string format: uuid
type
required
string
Allowed value: duplicate_payment_contact

Example

{
"error": {
"type": "duplicate_payment_contact"
}
}

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
"error": {
"details": "example",
"message": "example",
"request_id": "example",
"step_up": {
"delivery": "example",
"expires_at": "2026-04-15T12:00:00Z",
"id": "example",
"match_code": "example",
"methods": [
"example"
],
"step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"webauthn": {
"allow_credentials": [
{
"id": "example",
"transports": [
"example"
],
"type": "example"
}
],
"challenge": "example",
"challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"rp_id": "example",
"timeout": 1,
"user_verification": "example"
}
},
"type": "example"
}
}

Too many requests

Media typeapplication/json
RateLimitedError
object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string
error
required
object
type
required
string
Allowed value: rate_limited

Example

{
"error": {
"type": "rate_limited"
}
}
Retry-After
required
string

How long to wait before retrying, expressed as delay seconds or an HTTP date

Unexpected server error

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
"error": {
"details": "example",
"message": "example",
"request_id": "example",
"step_up": {
"delivery": "example",
"expires_at": "2026-04-15T12:00:00Z",
"id": "example",
"match_code": "example",
"methods": [
"example"
],
"step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"webauthn": {
"allow_credentials": [
{
"id": "example",
"transports": [
"example"
],
"type": "example"
}
],
"challenge": "example",
"challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"rp_id": "example",
"timeout": 1,
"user_verification": "example"
}
},
"type": "example"
}
}