Recipient API

The Recipient API allows you to 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.

Attribute

Name Type Description
object string

The string recipient.

id object_id

The RECIPIENT_ID 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.

active boolean

Whether the recipient is active.

bank_account bank_account

Destination bank account for transfer.

created datetime

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

description string

Description of the recipient.

email string

Email address associated with the recipient.

failure_code string

Failure code if status == failed. See testing for possible codes.

name string

Recipient name.

tax_id string

Recipient tax ID.

type string

Recipient type. One of individual or corporation.

verified boolean

Whether the recipient is verified.

Example

  • Json Response

List all recipients

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

Returns a list of all recipient objects belonging to your account.

Request Parameter

Name Type Description
offset integer

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

limit integer

(optional, default: 20, maximum: 100) Number of records to return.

from datetime

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

to datetime

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

order string

(optional, default: chronological) Order in which to return records. One of chronological (earliest to latest) or reverse_chronological (latest to earliest).

Example

  • List all recipients

Create a recipient

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

Returns a new recipient.

Request Parameter

Name Type Description
name string

(required) The recipient's name.

type string

(required) One of individual or corporation.

bank_account[name] string

(required) The bank account name.

bank_account[number] string

(required) The bank account number.

bank_account[brand] string

(optional) The bank account brand (required for banks in Thailand and Singapore).

See supported banks for allowed values.

bank_account[account_type] string

(optional) The type of account (required for banks in Japan). One of normal or current.

See supported banks for allowed values.

bank_account[bank_code] string

(optional) The bank code (required for banks in Japan).

bank_account[branch_code] string

(optional) The branch code (required for banks in Japan).

email string

(optional) Email to attach to the recipient.

description string

(optional) Description to attach to the recipient.

tax_id string

(optional) The recipient's tax ID.

Example

  • Create a recipient

Retrieve a recipient

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

Returns an existing recipient.

Example

  • Retrieve a recipient

Update a recipient

- PATCH https://api.omise.co/recipients/RECIPIENT_ID

Returns an updated recipient

Request Parameter

Name Type Description
name string

(optional) The recipient's name.

email string

(optional) Email to attach to the recipient.

description string

(optional) Description to attach to the recipient.

type string

(optional) One of individual or corporation.

tax_id string

(optional) The recipient's tax ID.

bank_account bank_account

(optional) A valid bank account object.

Example

  • Update a recipient

Destroy a recipient

- DELETE https://api.omise.co/recipients/RECIPIENT_ID

Destroys a recipient.

Example

  • Destroy a recipient