Recipient API

Recipient API สามารถใช้เพื่อสร้าง, เรียกข้อมูล, อัปเดต และลบผู้รับเงินสำหรับรายการโอนเงินทั้งที่เป็นแบบโอนเงินครั้งเดียว หรือการโอนเงินแบบอัตโนมัติ ผู้รับเงินสามารถเป็นได้ทั้งบุคคลธรรมดาหรือนิติบุคคล โดยจะต้องมีบัญชีธนาคารที่ได้รับการตรวจสอบและอนุมัติการใช้งานจากโอมิเซะแล้ว

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_at	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`.
metadata	object	Custom metadata (e.g. `{"answer": 42}`) for recipient.
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

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

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[bank_code]	string	(optional, but conditionally required) Bank code. Required for Omise accounts registered in Japan.
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 code. Required for Omise accounts registered in Thailand and Singapore.
bank_account[type]	string	(optional, but conditionally required) Type of bank account. One of `normal` or `current`. Required for Omise accounts registered in Japan.
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)

curl
ruby
python
php
C#
node.js
java
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"

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"
  }
})

import omise

omise.api_secret = 'skey_test_4xs8breq3htbkj03d2x'

recipient = omise.Recipient.create(
    name='Somchai Prasert',
    email='somchai.prasert@example.com',
    type='individual',
    bank_account=dict(
        brand='bbl',
        number='1234567890',
        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'
  )
));

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}");

omise.recipients.create({
  'name': 'Somchai Prasert',
  'email': 'somchai.prasert@example.com',
  'type': 'individual',
  'bank_account': {
    'brand': 'bbl',
    'number': '1234567890',
    'name': 'SOMCHAI PRASERT'
  }
}, function(err, resp) {
  /* Response. */
});

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());

recipient, create := &omise.Recipient{}, &operations.CreateRecipient{
	Name:        "Somchai Prasert",
	Email:       "somchai.prasert@example.com",
	Type:        omise.Individual,
	BankAccount: &omise.BankAccount{
		Brand:  "BBL",
		Number: "123456789",
		Name:   "SOMCHAI PRASERT",
	},
}
if e := client.Do(recipient, create); e != nil {
	log.Fatalln(e)
}

log.Printf("created recipient: %#v\n", recipient)

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
ruby
python
php
C#
node.js
java
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 "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"

Retrieve a recipient

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

Returns the recipient matching :id.

Example

Retrieve a recipient

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

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

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

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

import omise

omise.api_secret = 'skey_test_4xs8breq3htbkj03d2x'

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

<?php

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

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

omise.recipients.retrieve("recp_test_5086xmr74vxs0ajpo78", function(err, resp){
  /* Response. */
});

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

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

recipient, retrieve := &omise.Recipient{}, &operations.RetrieveRecipients{
	RecipientID: "recp_test_5086xmr74vxs0ajpo78",
}
if e := client.Do(recipient, retrieve); e != nil {
	log.Fatalln(e)
}

log.Printf("recipient: %#v\n", recipient)

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

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

curl
ruby
python
php
C#
node.js
java
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"

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"
  }
})

import omise

omise.api_secret = 'skey_test_4xs8breq3htbkj03d2x'

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

<?php

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

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}");

omise.recipients.update("recp_test_5086xmr74vxs0ajpo78",
{
  "email": "somchai@prasert.com",
  "bank_account": {
    "brand": "kbank",
    "number": "1234567890",
    "name": "SOMCHAI PRASERT"
  }
}, function(err, resp){
  /* Response. */
});

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());

recipient, update := &omise.Recipient{}, &operations.UpdateRecipient{
	RecipientID: "recp_test_5086xmr74vxs0ajpo78",
	Email:       "somchai@prasert.com",
	BankAccount: &omise.BankAccount{
		Brand:  "KBANK",
		Number: "1234567890",
		Name:   "Somechai Prasert",
	},
}

if e := client.Do(recipient, update); e != nil {
	log.Fatalln(e)
}

log.Printf("updated recipient: %#v\n", recipient)

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"
  ]
])

Destroy a recipient

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

Destroys the recipient matching :id.

Example

Destroy a recipient

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

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

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

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

import omise

omise.api_secret = 'skey_test_4xs8breq3htbkj03d2x'

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

<?php

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

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

omise.recipients.destroy("recp_test_5086xmr74vxs0ajpo78", function(err, resp) {
  /* Response. */
});

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

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

model, destroy := &omise.Deletion{}, &operations.DestroyRecipient{
	RecipientID: "recp_test_5086xmr74vxs0ajpo78",
}

if e := client.Do(model, destroy); e != nil {
	log.Fatalln(e)
}

log.Printf("destroyed recipient:", model.ID)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Recipient.destroy("recp_test_5086xmr74vxs0ajpo78")

JSON Response

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

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

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

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

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

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

recipients = Omise::Recipient.list

import omise

omise.api_secret = 'skey_test_4xs8breq3htbkj03d2x'

recipients = omise.Recipient.retrieve()

<?php

$recipient = OmiseRecipient::retrieve();

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

omise.recipients.list(function(err, resp) {
  /* Response. */
});

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

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

recipients, list := &omise.RecipientList{}, &operations.ListRecipient{
	operations.List{
		Offset: 100,
		Limit:  20,
	},
}

if e := client.Do(recipients, list); e != nil {
	log.Fatalln(e)
}

log.Printf("recipients #100-#120: %#v\n", recipients.Data)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Recipient.list

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

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

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