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 object_id

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 datetime

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 datetime

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.

name string

Recipient name.

schedule transfer_schedule

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 datetime

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[name] string

(required) Bank account holder name.

bank_account[number] string

(required) Bank account number.

name string

(required) Recipient name.

type string

(required) Recipient type. One of individual or corporation.

bank_account[account_type] string

(optional, but conditionally required) Type of bank account. One of normal or current (Japan only).

bank_account[bank_code] string

(optional, but conditionally required) Bank code (Japan only).

bank_account[branch_code] string

(optional, but conditionally required) Branch code. Required for Omise accounts registered in Japan.

bank_account[brand] string

(optional, but conditionally required) Bank account brand. Required for Omise accounts registered in Thailand and Singapore.

description string

(optional) Recipient description.

email string

(optional) Recipient email address.

tax_id string

(optional) Recipient tax ID.

Example

  • Create a recipient (Thailand and Singapore)

  • Create a recipient (Japan)

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
name string

(optional) Recipient name.

type string

(optional) Recipient type. One of individual or corporation.

bank_account bank_account

(optional) Destination bank account for transfer.

description string

(optional) Recipient description.

email string

(optional) Recipient email address.

tax_id string

(optional) Recipient tax ID.

Example

  • Update a recipient

Destroy a recipient

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

Destroys the recipient matching :id.

Example

  • Destroy a recipient

  • JSON Response

List recipients

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

Returns a list of recipients belonging to your account.

Request Parameters

Name Type Description
from datetime

(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, maximum: 100) 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) Order of records returned. One of chronological (earliest to latest) or reverse_chronological (latest to earliest).

to datetime

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

Example

  • List all recipients

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