Recipient API

Create, retrieve, update, and delete recipients of one-time transfers or transfer schedules. Recipients may be individuals or corporations, and must have a valid bank account associated.

Attributes

Name Type Description
object string

The string recipient.

id string

The recipient identifier matching /recp(_test)?_[0-9a-z]+/.

livemode boolean

Whether this is a live (true) or test (false) recipient.

location string

API path to retrieve the current recipient object.

activated_at string

UTC datetime of the activation of the recipient in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

active boolean

Whether recipient is active.

bank_account bank_account

Destination bank account for transfer.

created_at string

UTC datetime of recipient creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

default boolean

Whether recipient is account default.

deleted boolean

Whether recipient is deleted.

description string

Recipient description.

email string

Recipient email address.

failure_code string

Recipient creation failure code. One of name_mismatch, account_not_found, or bank_not_found.

metadata object

Custom metadata (e.g. {"answer": 42}) for recipient.

name string

Recipient name.

schedule object_id_expandable

Transfer schedule associated with recipient.

tax_id string

Recipient tax ID.

type string

Recipient type. One of individual or corporation.

verified boolean

Whether recipient is verified.

verified_at string

UTC datetime of the verification of the recipient in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Example

  • JSON Response

Create a recipient

- POST https://api.omise.co/recipients

Creates and returns a new recipient.

Request Parameters

Name Type Description
bank_account object

(optional) Destination bank account for transfer.

description string

(optional) Recipient description.

email string

(optional) Recipient email address.

metadata object

(optional) Custom metadata (e.g. {"answer": 42}) for recipient.

name string

(optional) Recipient name.

tax_id string

(optional) Recipient tax ID.

type string

(optional, one of: individual, corporation) Recipient type.

Example

  • Create a recipient (Thailand and Singapore)

  • Create a recipient (Japan)

Destroy a recipient

- DELETE https://api.omise.co/recipients/{id}

Destroys the recipient matching :id.

Example

  • Destroy a recipient

List recipients

- GET https://api.omise.co/recipients

Returns a list of recipients belonging to your account.

Request Parameters

Name Type Description
from string

(optional, default: 1970-01-01T00:00:00Z) Earliest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

limit integer

(optional, default: 20) Number of records returned.

offset integer

(optional, default: 0) Offset of the first record returned (i.e. how many records to skip from the beginning).

order string

(optional, default: chronological, one of: chronological, reverse_chronological) Order of records returned.

to string

(optional) Latest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Example

  • List all recipients

Retrieve a recipient

- GET https://api.omise.co/recipients/{id}

Returns the recipient matching :id.

Example

  • Retrieve a recipient

Update a recipient

- PATCH https://api.omise.co/recipients/{id}

Returns an updated recipient

Request Parameters

Name Type Description
bank_account object

(optional) Destination bank account for transfer.

description string

(optional) Recipient description.

email string

(optional) Recipient email address.

metadata object

(optional) Custom metadata (e.g. {"answer": 42}) for recipient.

name string

(optional) Recipient name.

tax_id string

(optional) Recipient tax ID.

type string

(optional, one of: individual, corporation) Recipient type.

Example

  • Update a recipient

Mark a recipient as verified

- PATCH https://api.omise.co/recipients/{id}/verify

This endpoint allows you to manually mark a recipient as verified. This can be useful for testing purposes.

Example

  • Verify a recipient

Omise uses cookies to improve your overall site experience and collect information on your visits and browsing behavior. By continuing to browse our website, you agree to our Privacy Policy. Learn more