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 verification failure code. One of `name_mismatch`, `account_not_found`, `bank_not_found`, `mule_account_match_at_creation`, `mule_account_match_at_edit`, `mule_account_match_at_transfer`, or `unable_to_verify_merchant_recipient_relationship`.
metadata	object	Custom metadata (e.g. `{"answer": 42}`) for recipient.
name	string	Recipient name.
recipient_relationships	array	Documents linked to the recipient. Each item has a `document_id`, a filename, and a `created_at` entity.
relationship_type	string	Merchant-recipient relationship. One of: `Partner`, `Vendor`, `Contractor`, `Employee`, or `Others`. Required when creating a non-default recipient for a PaaS user on PSP Thailand. Cannot be updated after creation.
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

{
  "object": "recipient",
  "id": "recp_test_no1t4tnemucod0e51mo",
  "livemode": false,
  "location": "/recipients/recp_test_no1t4tnemucod0e51mo",
  "deleted": false,
  "bank_account": {
    "object": "bank_account",
    "livemode": false,
    "last_digits": "1234",
    "account_number": "1234",
    "name": "Somchai Prasert",
    "type": null,
    "created_at": "2019-12-31T12:59:59Z",
    "brand": "Bangkok Bank",
    "bank_code": "bbl",
    "branch_code": null
  },
  "active": true,
  "default": false,
  "verified": false,
  "description": null,
  "email": "somchai.prasert@example.com",
  "failure_code": null,
  "name": "Somchai Prasert",
  "tax_id": null,
  "type": "individual",
  "created_at": "2019-12-31T12:59:59Z",
  "schedule": null,
  "metadata": {},
  "verified_at": null,
  "activated_at": "2019-12-31T12:59:59Z"
}

Create a recipient

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

Creates and returns a new recipient.

Error info

HTTP	Message	Reason
400	relationship_type is required for this account	PaaS Thailand create without type
400	document_ids is required for this account	PaaS Thailand create without documents
400	relationship_type must be one of Partner, Vendor, Contractor, Employee, or Others: <text>	Invalid type, including bare Others
400	relationship_type is too long (maximum is 256 characters)	Type exceeds 256
400	cannot exceed 10 relationship documents	Over the cap
400	duplicate filename	Two files share a filename
400	document is already linked to a recipient	Reuse of a live document
400	document {id} is not available for linking	Not a temp unlinked document
400	recipient management via API is not available for this account	Pre-PaaS restriction
400	recipient creation via API is not available for this account	PaaS account not allowed to create non-default recipients

Request Parameters

Name	Type	Description
bank_account	object	(optional) Destination bank account for transfer.
description	string	(optional) Recipient description.
document_ids	array	(optional) (Required for PaaS users, PSP Thailand) Document IDs from `POST /recipients/upload_relationship_document`.
email	string	(optional) Recipient email address.
metadata	object	(optional) Custom metadata (e.g. `{"answer": 42}`) for recipient.
name	string	(optional) Recipient name.
relationship_type	string	(optional) (Required for PaaS users, PSP Thailand) One of: `Partner`, `Vendor`, `Contractor`, `Employee`, or `Others`.
tax_id	string	(optional) Recipient tax ID.
type	string	(optional, one of: `individual`, `corporation`) Recipient type.

Example

Create a recipient (Singapore)

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/recipients \
  -u $OMISE_SECRET_KEY: \
  -d "name=Somchai Prasert" \
  -d "email=somchai.prasert@example.com" \
  -d "description=Additional information about Somchai Prasert." \
  -d "type=individual" \
  -d "tax_id=1234567890" \
  -d "bank_account[brand]=bbl" \
  -d "bank_account[number]=acc12345" \
  -d "bank_account[name]=Somchai Prasert"

<?php

$recipient = OmiseRecipient::create(array(
  'name' => 'Omise Tester',
  'description' => 'Tester account',
  'email' => 'tester@omise.co',
  'type' => 'individual',
  'tax_id' => '',
  'bank_account' => array(
    'brand' => 'bbl',
    'number' => '1234567890',
    'name' => 'Tester Account'
  )
));

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const recp = await omise.recipients.create({
  name: 'Somchai Prasert',
  email: 'somchai.prasert@example.com',
  type: 'individual',
  bank_account: {
    brand: 'bbl',
    number: '1234567890',
    name: 'SOMCHAI PRASERT',
  },
});
console.log(recp);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

recipient = Omise::Recipient.create({
  name: "Somchai Prasert",
  email: "somchai.prasert@example.com",
  type: "individual",
  bank_account: {
    brand: "bbl",
    number: "1234567890",
    name: "SOMCHAI PRASERT"
  }
})

var recipient = await Client.Recipients.Create(new CreateRecipientRequest
{
    Name = "John Doe",
    Email = "john.doe@example.com",
    Description = "John Doe (user: 30)",
    Type = RecipientType.Individual,
    BankAccount = new BankAccountRequest
    {
        Brand = "kbank",
        Number = "7777777777",
        Name = "Dohn Joe",
    },
});

Console.WriteLine($"created recipient: {recipient.Id}");

Request<Recipient> request = new Recipient.CreateRequestBuilder()
        .name("John Doe")
        .email("john.doe@omise.co")
        .type(RecipientType.Individual)
        .bankAccount(new BankAccount.Params()
                            .brand("bbl")
                            .number("1234567890")
                            .name("SOMCHAI PRASErT"))
        .build();
Recipient recipient = client().sendRequest(request);

System.out.printf("Created recipient: %s", recipient.getId());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

recipient = omise.Recipient.create(
    name="Somchai Prasert",
    email="somchai.prasert@example.com",
    type="individual",
    bank_account=dict(brand="bbl", number="1234567890", name="SOMCHAI PRASERT"),
)

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Recipient{}

err := client.Do(result, &operations.CreateRecipient{
	Name:  "Somchai Prasert",
	Email: "somchai.prasert@example.com",
	Type:  omise.Individual,
	BankAccount: &omise.BankAccount{
		Brand:  "bbl",
		Number: "123456789",
		Name:   "SOMCHAI PRASERT",
	},
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Recipient.create(
  name:  "Somchai Prasert",
  email: "somchai.prasert@example.com",
  type:  "individual",
  bank_account: [
    brand:  "bbl",
    number: "1234567890",
    name:   "SOMCHAI PRASERT"
  ]
)

Create a recipient (Japan)

curl

curl https://api.omise.co/recipients \
  -u $OMISE_SECRET_KEY: \
  -d "name=Somchai Prasert" \
  -d "email=somchai.prasert@example.com" \
  -d "description=Additional information about Somchai Prasert." \
  -d "type=individual" \
  -d "bank_account[bank_code]=0001" \
  -d "bank_account[branch_code]=001" \
  -d "bank_account[account_type]=normal" \
  -d "bank_account[number]=0000001" \
  -d "bank_account[name]=Somchai Prasert"

Destroy a recipient

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

Destroys the recipient matching :id.

Example

Destroy a recipient

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/recipients/recp_test_5g03h1x1mbpgxp8h1fh \
  -X DELETE \
  -u $OMISE_SECRET_KEY:

<?php

$recipient = OmiseRecipient::retrieve('recp_test_4z6p7e0m4k40txecj5o');
$recipient->destroy();

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const recp = await omise.recipients.destroy('recp_test_no1t4tnemucod0e51mo');
console.log(recp);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

recipient = Omise::Recipient.retrieve("recp_test_5086xmr74vxs0ajpo78")
recipient.destroy

var recipient = RetrieveRecipient();
recipient = await Client.Recipients.Destroy(recipient.Id);
Console.WriteLine($"destroyed recipient: {recipient.Id} ({recipient.Deleted})");

Request<Recipient> request =
        new Recipient.DeleteRequestBuilder("recp_test_4z6p7e0m4k40txecj5o").build();
Recipient recipient = client().sendRequest(request);

System.out.printf("Destroyed recipient: %s", recipient.getId());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

recipient = omise.Recipient.retrieve("recp_test_no1t4tnemucod0e51mo")
recipient.destroy()

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Deletion{}

err := client.Do(result, &operations.DestroyRecipient{
	RecipientID: "recp_test_no1t4tnemucod0e51mo",
})

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Recipient.destroy("recp_test_5086xmr74vxs0ajpo78")

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

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/recipients \
  -u $OMISE_SECRET_KEY:

<?php

$recipient = OmiseRecipient::retrieve();

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const recp = await omise.recipients.list();
console.log(recp);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

recipients = Omise::Recipient.list

var recipients = await Client.Recipients.GetList(order: Ordering.ReverseChronological);
Console.WriteLine($"total recipients: {recipients.Total}");

Request<ScopedList<Recipient>> request = new Recipient.ListRequestBuilder().build();
ScopedList<Recipient> recipients = client().sendRequest(request);

System.out.printf("Total no. of recipients: %d", recipients.getTotal());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

recipients = omise.Recipient.retrieve()

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.RecipientList{}

err := client.Do(result, &operations.ListRecipients{
	operations.List{
		Offset: 100,
		Limit:  20,
	},
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Recipient.list

Retrieve a recipient

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

Returns the recipient matching :id.

Example

Retrieve a recipient

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/recipients/recp_test_5g03h1x1mbpgxp8h1fh \
  -u $OMISE_SECRET_KEY:

<?php

$recipient = OmiseRecipient::retrieve('recp_test_4z6p7e0m4k40txecj5o');

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const recp = await omise.recipients.retrieve('recp_test_no1t4tnemucod0e51mo');
console.log(recp);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

recipient = Omise::Recipient.retrieve("recp_test_5086xmr74vxs0ajpo78")

var recipientId = "recp_test_57po4c5obpi7rrxhtyl";
var recipient = await Client.Recipients.Get(recipientId);
Console.WriteLine($"recipient account last digits: {recipient.BankAccount.LastDigits}");

Request<Recipient> request =
        new Recipient.GetRequestBuilder("recp_test_4z6p7e0m4k40txecj5o").build();
Recipient recipient = client().sendRequest(request);

System.out.printf("Recipient's email: %s", recipient.getEmail());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

recipient = omise.Recipient.retrieve("recp_test_no1t4tnemucod0e51mo")

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Recipient{}

err := client.Do(result, &operations.RetrieveRecipient{
	RecipientID: "recp_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Recipient.retrieve("recp_test_5086xmr74vxs0ajpo78")

Update a recipient

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

Returns an updated recipient.

Error info

HTTP	Message	Reason
400	relationship_type cannot be updated	Update includes the field
400	document_ids cannot be updated	Update includes the field
400	recipient management via API is not available for this account	Pre-PaaS restriction
400	recipient update via API is not available for this account	PaaS restriction on non-default recipient

Request Parameters

Name	Type	Description
bank_account	object	(optional) Destination bank account for transfer.
description	string	(optional) Recipient description.
document_ids	array	(optional) (Required for PaaS users, PSP Thailand) Document IDs from `POST /recipients/upload_relationship_document`.
email	string	(optional) Recipient email address.
metadata	object	(optional) Custom metadata (e.g. `{"answer": 42}`) for recipient.
name	string	(optional) Recipient name.
relationship_type	string	(optional) (Required for PaaS users, PSP Thailand) One of: `Partner`, `Vendor`, `Contractor`, `Employee`, or `Others`.
tax_id	string	(optional) Recipient tax ID.
type	string	(optional, one of: `individual`, `corporation`) Recipient type.

Example

Update a recipient

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/recipients/recp_test_5g03h1x1mbpgxp8h1fh \
  -X PATCH \
  -u $OMISE_SECRET_KEY: \
  -d "name=John Smith" \
  -d "email=somchai.prasert@example.com" \
  -d "bank_account[number]=acc123456789"

<?php

$recipient = OmiseRecipient::retrieve('recp_test_4z6p7e0m4k40txecj5o');
$recipient->update(array(
  'name' => 'Omise Tester',
  'email' => 'tester@omise.co',
  'description' => 'Another description'
));

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const recp = await omise.recipients.update(
  'recp_test_no1t4tnemucod0e51mo',
  {
    email: 'somchai@prasert.com',
    bank_account: {
      brand: 'kbank',
      number: '1234567890',
      name: 'SOMCHAI PRASERT',
    },
  },
);
console.log(recp);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

recipient = Omise::Recipient.retrieve("recp_test_5086xmr74vxs0ajpo78")
recipient.update({
  email: "somchai@prasert.com",
  bank_account: {
    brand: "kbank",
    number: "1234567890",
    name: "SOMCHAI PRASERT"
  }
})

var recipientId = "recp_test_57po4c5obpi7rrxhtyl";
var recipient = await Client.Recipients.Update(recipientId, new UpdateRecipientRequest
{
    Name = "Dohn Joe",
    Email = "dohn.joe@example.com",
});

Console.WriteLine($"updated recipient: {recipient.Id}");

Request<Recipient> request = new Recipient.UpdateRequestBuilder("recp_test_4z6p7e0m4k40txecj5")
        .email("somchai@prasert.com")
        .bankAccount(new BankAccount.Params()
        .brand("kbank")
        .number("1234567890")
        .name("SOMCHAI PRASERT"))
        .build();
Recipient recipient = client().sendRequest(request);

System.out.printf("Updated recipient: %s", recipient.getId());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

recipient = omise.Recipient.retrieve("recp_test_no1t4tnemucod0e51mo")
recipient.update(
    email="somchai@prasert.com",
    bank_account=dict(brand="kbank", number="1234567890", name="SOMCHAI PRASERT"),
)

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Recipient{}

err := client.Do(result, &operations.UpdateRecipient{
	RecipientID: "recp_test_no1t4tnemucod0e51mo",
	Email:       "somchai@prasert.com",
	BankAccount: &omise.BankAccount{
		Brand:  "kbank",
		Number: "1234567890",
		Name:   "Somechai Prasert",
	},
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Recipient.update("recp_test_5086xmr74vxs0ajpo78", [
  email: "somchai@prasert.com",
  bank_account: [
    brand:  "kbank",
    number: "1234567890",
    name:   "SOMCHAI PRASERT"
  ]
])

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. This endpoint works in test mode only. A live recipient returns recipient is not in test mode.

Error info

HTTP	Message	Reason
400	recipient is not in test mode	Verify on a live recipient

Example

Verify a recipient

curl
node.js

curl https://api.omise.co/recipients/recp_test_5g03h1x1mbpgxp8h1fh/verify \
  -X PATCH \
  -u $OMISE_SECRET_KEY:

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const recp = await omise.recipients.verify('recp_test_no1t4tnemucod0e51mo');
console.log(recp);