Create a Linked Account

POSThttps://api.omise.co/linked_accounts

Create a new linked account to initiate payment method registration. The response includes a registration_uri where the account holder can complete the registration process.

---

Request Parameters

Required - 2 fieldsRequired Parameters

▼

`type`STRING(required)

Type of linked account. Available types depend on the payment method (e.g., direct_debit_kbank, direct_debit_scb, direct_debit_bbl for Thai banks).

Example:"direct_debit_kbank"

`return_uri`STRING(required)

URI to redirect the account holder after completing the registration process.

Example:"https://example.com/linked-accounts/complete"

Optional - 2 fieldsOptional Parameters

▼

---

Responses

200

Linked account created successfully

Linked account created. Redirect the account holder to the registration_uri to complete registration.

Linked account object fields:

• object - Always "linked_account"
• id - Linked account ID (lacct_*). Store this in your database.
• livemode - Whether this is a live or test mode linked account
• status - Account status: failed, expired, pending, successful, or deleted
• type - Type of linked account
• last_digits - Last digits of the linked account identifier (if applicable)
• registration_uri - URI where the account holder completes registration
• return_uri - URI to redirect after registration
• expires_at - When the registration link expires
• created_at - Linked account creation timestamp
• registered_at - When registration was completed (null if pending)
• failure_code - Error code if registration failed (null if not failed)
• failure_message - Error message if registration failed (null if not failed)
• metadata - Custom key-value data

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Missing required parameter (type or return_uri)
• Invalid type value
• Invalid return_uri format
• Invalid citizen_id format
• Metadata exceeds 15,000 characters

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key
• Incorrect HTTP Basic Auth format

422

Unprocessable entity

The request was valid but could not be processed.

Common causes:

• Linked account type not enabled for your account
• Account limit reached
• Payment method not available in your region

5xx

Server error

Server-side error occurred. These are rare but should be handled gracefully.

How to handle:

• Retry the request with exponential backoff
• Check status.omise.co for service incidents
• See Error Handling for detailed guidance

---

Code samples

cURL

curl https://api.omise.co/linked_accounts \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -d "type=direct_debit_kbank" \
  -d "return_uri=https://example.com/linked-accounts/complete"

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

linked_account = Omise::LinkedAccount.create({
  type: 'direct_debit_kbank',
  return_uri: 'https://example.com/linked-accounts/complete'
})

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

linked_account = omise.LinkedAccount.create(
    type='direct_debit_kbank',
    return_uri='https://example.com/linked-accounts/complete'
)

Node.js

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

const linkedAccount = await omise.linkedAccounts.create({
  type: 'direct_debit_kbank',
  return_uri: 'https://example.com/linked-accounts/complete'
});

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$linked_account = OmiseLinkedAccount::create([
    'type' => 'direct_debit_kbank',
    'return_uri' => 'https://example.com/linked-accounts/complete'
]);

Java

Client client = new Client.Builder()
    .secretKey("skey_test_5xuy4w91xqz7d1w9u0t")
    .build();

LinkedAccount linkedAccount = client.linkedAccounts().create()
    .type("direct_debit_kbank")
    .returnUri("https://example.com/linked-accounts/complete")
    .send();

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var linkedAccount = await client.LinkedAccounts.Create(new CreateLinkedAccountRequest
{
    Type = "direct_debit_kbank",
    ReturnUri = "https://example.com/linked-accounts/complete"
});

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "skey_test_5xuy4w91xqz7d1w9u0t",
)

linkedAccount, _ := client.LinkedAccounts().Create(&operations.CreateLinkedAccount{
    Type:      "direct_debit_kbank",
    ReturnUri: "https://example.com/linked-accounts/complete",
})

---

Error and result codes

Common Error Codes

Code	Description	Resolution
bad_request	Missing or invalid parameters	Check that type and return_uri are valid
authentication_failure	Invalid API key	Verify your secret key is correct
invalid_linked_account_type	Type not supported	Check available linked account types
not_enabled	Feature not enabled	Contact support to enable linked accounts

Linked Account Status Values

Status	Description
pending	Registration in progress, awaiting completion
successful	Registration completed successfully
failed	Registration failed (check failure_code and failure_message)
expired	Registration link expired before completion
deleted	Linked account has been deleted

Linked Account Fields

Field	Description
id	Linked account ID (store this in your database)
type	Type of linked account
status	Current status of the linked account
registration_uri	URL for account holder to complete registration
return_uri	Redirect URL after registration
last_digits	Last digits of the account identifier
expires_at	Expiration time for registration link
registered_at	When registration was completed
failure_code	Error code if registration failed
failure_message	Human-readable error message
metadata	Custom key-value data
created_at	Linked account creation timestamp

---

🔑API Credentials

▼

Try it out

Required - 2 fields

▼

type(Required)

return_uri(Required)

Additional - 2 fields

▼

Your IP: ...Loading...