Skip to main content
POST
finance.beneficiary.get

Authorizations

Authorization
string
header
required

API key: sk_live_…

Headers

Idempotency-Key
string

Optional. A retry with the same key returns the stored result.

Maximum string length: 255
Pramaan-Account
string

Optional. One of your account ids (GET /v1/accounts): run on that account, whatever your routing rules say. The response header X-Pramaan-Account names the account that ran.

Pramaan-End-User
string

Optional. Your own tag for your end user: a sticky: end_user rule keeps them on the account that first served them.

Maximum string length: 256
Pramaan-End-User-Group
string

Optional. Your end user's group, matched by rules with endUserGroup.

Maximum string length: 64

Body

application/json
beneficiaryId
string
required

Your beneficiary record ID.

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]+$
accountId
string

Connected sub-account; omit to use your own account.

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]+$

Response

The result

beneficiaryId
string
required

Your beneficiary record ID, for follow-up calls.

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]+$
name
string
required

Beneficiary name.

Required string length: 1 - 100
status
enum<string>
required

Account's reported beneficiary state; saved means the account accepted the details and has no separate verification step.

Available options:
pending,
saved,
verified,
invalid,
canceled,
failed,
deleted,
unknown
verificationOffered
boolean

Whether this account verifies saved beneficiaries itself, so status can become verified. When false, saved is the final usable state.

bank
object

Bank details, typed by scheme.

currency
string

Currency of the bank account, when known.

Required string length: 1 - 3
bankAccount
string

Bank account number or IBAN, when present; the same as in bank.

Required string length: 1 - 34
routingCode
string

Bank routing code, when the scheme has one; the same as in bank.

Required string length: 1 - 34
paymentAddress
string

Payment address, when present.

Required string length: 1 - 256
email
string

Beneficiary email, when present.

Required string length: 1 - 320
phone
string

Beneficiary phone, when present.

Required string length: 1 - 32
entityType
enum<string>

Person or company.

Available options:
individual,
company
nickname
string

Your label for the recipient.

Required string length: 1 - 200
createdAt
string<date-time>

Date and time with timezone, ISO 8601.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$