Linked Account Object API NEW

Topics covered on this page

Objects and Endpoints
Linked account object attributes
Create a linked account object
Retrieve a linked account object
Delete a linked account object

Enable secure and seamless purchases directly from your customers' bank accounts using Direct Debit. Customers can link their bank account to your website or application for faster checkout, eliminating the need to enter payment details for future purchases.

This document explains the Linked Accounts Object API functions.

Objects and Endpoints

Object	Endpoint
linked_account: The account to link for direct debit.	POST /linked_accounts GET /linked_accounts/{id} DELETE /linked_accounts/{id}

Linked account object attributes

object
string
The linked_account object.

id
string
The linked account object identifier matching /lnac(_test)?_[0-9a-z]+/.

livemode
boolean
Identifies whether this is a live (true) or test (false) linked account.

location
string
The API path to retrieve the current linked_account object.

registration_uri
string
The URI to which the customer is redirected to perform the registration.

return_uri
string
The URI to which the customer is redirected after registration is completed.

type
string
The type of the linked account. This value depends on the payment method used.

status
string
The status of the linked account. Value can be one of failed, expired, pending, successful, or deleted.

last_digits
string
The last four digits of the account.

metadata
string
Custom metadata (e.g. {"answer": 42}) for the linked account.

failure_code
string
The failure code if status == failed. See the individual payment methods for possible codes.

failure_message
string
Message describing the failure if status == failed.

registered_at
string
UTC datetime of linked account registration in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

expires_at
string
UTC datetime of linked account expiration in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

created_at
string
UTC datetime of linked account creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Response on Success

{
    "object": "linked_account",
    "id": "lnac_test_5zylnmmt2kl9chq3ip1",
    "livemode": false,
    "location": "/linked_accounts/lnac_test_5zylnmmt2kl9chq3ip1",
    "registration_uri": "http://test.staging-omise.co/register?ref=lnac_test_5zylnmmt2kl9",
    "return_uri": "https://example.com/accounts/345678/complete",
    "type": "direct_debit_kbank",
    "status": "pending",
    "last_digits": null,
    "metadata": {},
    "failure_code": null,
    "failure_message": null,
    "registered_at": null,
    "expires_at": "2024-06-04T04:11:14Z",
    "created_at": "2024-06-03T04:11:14Z"
}

Create a linked account object

Create a linked account object that you can use to link an account for direct debit.

Linked account object creation example call

Curl example:

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

Linked account creation parameters

[Required] return_uri
string
The URI to which the customer is redirected after registration is completed.

[Required] type
string
The type of the linked account. This value depends on the payment method used.

[Optional] citizen_id
string
The ID of the account holder.

Response on Success

{
    "object": "linked_account",
    "id": "lnac_test_5zylnmmt2kl9chq3ip1",
    "livemode": false,
    "location": "/linked_accounts/lnac_test_5zylnmmt2kl9chq3ip1",
    "registration_uri": "http://test.staging-omise.co/register?ref=lnac_test_5zylnmmt2kl9",
    "return_uri": "https://example.com/accounts/345678/complete",
    "type": "direct_debit_kbank",
    "status": "pending",
    "last_digits": null,
    "metadata": {},
    "failure_code": null,
    "failure_message": null,
    "registered_at": null,
    "expires_at": "2024-06-04T04:11:14Z",
    "created_at": "2024-06-03T04:11:14Z"
    }

Linked account creation response codes

Code

Example

200 - OK

See Response on Success

400 - Bad Request
Check whether the required parameters are valid.

{
    "object": "error",
    "location": "https://www.omise.co/api-errors#bad-request",
    "code": "bad_request",
    "message": "Type is not supported"
}

{
    "object": "error",
    "location": "https://www.omise.co/api-errors#bad-request",
    "code": "bad_request",
    "message": "Type is required"
}

{
    "object": "error",
    "location": "https://www.omise.co/api-errors#bad-request",
    "code": "bad_request",
    "message": "Return uri is not a valid URI"
}

{
    "object": "error",
    "location": "https://www.omise.co/api-errors#bad-request",
    "code": "bad_request",
    "message": "Return uri is required"
}

401 - Unauthorized
Check whether the authentication key is valid.

{
    "object": "error",
    "location": "https://www.omise.co/api-errors#authentication-failure",
    "code": "authentication_failure",
    "message": "authentication failed"
}

Retrieve a linked account object

Retrieves the details of a linked account object.

Linked account object retrieval example call

Curl example:

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

Retrieve a linked account object with ID lnac_test_5zylnmmt2kl9chq3ip1.

Linked account object retrieval parameters

[Required] id
string
The ID of the linked account object to retrieve.

Response on Success

{
    "object": "linked_account",
    "id": "lnac_test_5zylnmmt2kl9chq3ip1",
    "livemode": false,
    "location": "/linked_accounts/lnac_test_5zylnmmt2kl9chq3ip1",
    "registration_uri": "http://test.staging-omise.co/register?ref=lnac_test_5zylnmmt2kl9chq3ip1",
    "return_uri": "https://example.com/accounts/345678/complete",
    "type": "direct_debit_kbank",
    "status": "pending",
    "last_digits": null,
    "metadata": {},
    "failure_code": null,
    "failure_message": null,
    "registered_at": null,
    "expires_at": "2024-06-04T04:11:14Z",
    "created_at": "2024-06-03T04:11:14Z"
}

Linked account object retrieval response codes

Code	Example
200 - OK	See Response on Success
401 - Unauthorized Check whether the authentication key is valid.	{ "object": "error", "location": "https://www.omise.co/api-errors#authentication-failure", "code": "authentication_failure", "message": "authentication failed" }
404 - Not found Check whether the ID is valid.	{ "object": "error", "location": "https://www.omise.co/api-errors#not-found", "code": "not_found", "message": "linked account lnac_test_5zylnmmt2kl9chq3i1 was not found" }
500 - Internal Server Error Check whether you have included the ID in the API call.	{ "status": 500, "error": "Internal Server Error" }

Delete a linked account object

Deletes a linked account object.

Linked account object deletion example call

Curl example:

curl https://api.omise.co/linked_accounts/lnac_test_5zylnmmt2kl9chq3ip1 \
  -X DELETE \
  -u $OMISE_SECRET_KEY:

Delete a linked account object with ID lnac_test_5zylnmmt2kl9chq3ip1.

Linked account object deletion parameters

[Required] id
string
The ID of the linked account object to delete.

Response on Success

{
    "object": "linked_account",
    "id": "lnac_test_5zz3p29a4lxkzvs2jim",
    "livemode": false,
    "location": "/linked_accounts/lnac_test_5zz3p29a4lxkzvs2jim",
    "registration_uri": "http://test.staging-omise.co/register?ref=lnac_test_5zz3p29a4lxkzvs2jim",
    "return_uri": "http://example.com/accounts/345678/complete",
    "type": "direct_debit_kbank",
    "status": "deleted",
    "last_digits": "7890",
    "metadata": {},
    "failure_code": null,
    "failure_message": null,
    "registered_at": "2024-06-04T10:56:45Z",
    "expires_at": "2024-06-05T10:56:07Z",
    "created_at": "2024-06-04T10:56:07Z"
}

Linked account object deletion response codes

Code	Example
200 - OK	See Response on Success
400 - Bad Request Check whether the linked account is registered.	{ "object": "error", "location": "https://www.omise.co/api-errors#bad-request", "code": "bad_request", "message": "linked account is not registered" }
401 - Unauthorized Check whether the authentication key is valid.	{ "object": "error", "location": "https://www.omise.co/api-errors#authentication-failure", "code": "authentication_failure", "message": "authentication failed" }
404 - Not found Check whether the ID is valid.	{ "object": "error", "location": "https://www.omise.co/api-errors#not-found", "code": "not_found", "message": "linked account lnac_test_5zylnmmt2kl9chq3i1 was not found" }
500 - Internal Server Error Check whether you have included the ID in the API call.	{ "status": 500, "error": "Internal Server Error" }