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)?_[1-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

The recipient's bank account.

created datetime

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

description string

The human-readable description of the recipient.

email string

Email address associated with the recipient.

failure_code string

The failure code if status == failed. See testing for possible codes.

name string

The recipient's name.

tax_id string

The recipient tax ID.

type string

The 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) The offset of the first record returned (i.e. how many records to skip from the beginning).

limit integer

(optional, default: 20, maximum: 100) The number of records returned.

from datetime

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

to datetime

(optional, default: current UTC datetime) The latest UTC date and time for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

order string

(optional, default: chronological) The order of the list returned. Either 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

The recipient's name

email string

(optional) The recipient's email

description string

(optional) The recipient's description

type string

Either individual or corporation

tax_id string

(optional) The recipient's tax id

bank_account bank_account

A valid bank account object

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) The recipient's email

description string

(optional) The recipient's description

type string

(optional) Either 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