Recipient API

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

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`).
default	boolean	Whether the recipient is the default.
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

{
  "object": "recipient",
  "id": "recp_test_5086xmr74vxs0ajpo78",
  "livemode": false,
  "location": "/recipients/recp_test_5086xmr74vxs0ajpo78",
  "verified": false,
  "active": false,
  "name": "Somchai Prasert",
  "email": "somchai.prasert@example.com",
  "description": null,
  "type": "individual",
  "tax_id": null,
  "bank_account": {
    "object": "bank_account",
    "brand": "bbl",
    "last_digits": "7890",
    "name": "SOMCHAI PRASERT",
    "created": "2015-06-02T05:41:53Z"
  },
  "failure_code": null,
  "created": "2015-06-02T05:41:53Z"
}

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

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

curl -X GET https://api.omise.co/recipients \
  -u skey_test_4xsjvwfnvb2g0l81sjz:

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. */
});

ScopedList<Recipient> recipients = client.recipients().list();
System.out.printf("returned recipients: %d", recipients.getData().size());
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

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

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

## For Thailand, Singapore, Indonesian
curl https://api.omise.co/recipients \
  -X POST \
  -u skey_test_4xsjvwfnvb2g0l81sjz: \
  -d "name=James Smith" \
  -d "email=test_recp123@localhost" \
  -d "description=My first other recipient" \
  -d "type=individual" \
  -d "tax_id=1234567890" \
  -d "bank_account[brand]=test" \
  -d "bank_account[number]=acc12345" \
  -d "bank_account[name]=James Smith"

## For Japan
curl https://api.omise.co/recipients \
  -X POST \
  -u skey_test_550b2hdgr0hzyzgldno: \
  -d "name=John Doe" \
  -d "email=john.doe@example.com" \
  -d "description=John Doe (id: 30)" \
  -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]=John Doe"

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. */
});

Recipient recipient = client.recipients()
  .create(new Recipient.Create()
          .name("Somchai Prasert")
          .email("somchai.prasert@example.com")
          .type(RecipientType.Individual)
          .bankAccount(new BankAccount.BankAccountParams()
                       .brand("bbl")
                       .number("1234567890")
                       .name("SOMCHAI PRASErT")));
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"
  ]
)

Retrieve a recipient

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

Returns an existing recipient.

Example

Retrieve a recipient

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

curl https://api.omise.co/recipients/recp_test_4z6p7e0m4k40txecj5o \
  -u skey_test_4xsjvwfnvb2g0l81sjz:

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. */
});

Recipient recipient = client.recipients().get("recp_test_4z6p7e0m4k40txecj5o");
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/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

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

curl https://api.omise.co/recipients/recp_test_4z6p7e0m4k40txecj5o \
  -X PATCH \
  -u skey_test_4xsjvwfnvb2g0l81sjz: \
  -d "name=John Smith" \
  -d "email=john.smith@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. */
});

Recipient recipient = client.recipients()
  .update("recp_test_4z6p7e0m4k40txecj5", new Recipient.Update()
          .email("somchai@prasert.com")
          .bankAccount(new BankAccount.BankAccountParams()
                       .brand("kbank")
                       .number("1234567890")
                       .name("SOMCHAI PRASERT")));
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"
  ]
])

Mark a recipient as verified in test mode

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

This endpoint allows you to manually mark a recipient as verified. This can be useful for testing purposes.

Destroy a recipient

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

Destroys a recipient.

Example

Destroy a recipient

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

curl https://api.omise.co/recipients/recp_test_4z6p7e0m4k40txecj5o \
  -X DELETE \
  -u skey_test_4xsjvwfnvb2g0l81sjz:

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. */
});

Recipient recipient = client.recipients().destroy("recp_test_4z6p7e0m4k40txecj5o");
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")