List Link Charges

GEThttps://api.omise.co/links/:link_id/charges

Retrieve a paginated list of all charges created from a specific payment link. Useful for tracking payments made through a particular link.

Request Parameters

Required - 1 fieldRequired Parameters

▼

`link_id`STRING(required)

Link identifier matching pattern /link(_test)?_[0-9a-z]+/. This is provided in the URL path.

Example:"link_test_5xuy4w91xqz7d1w9u0t"

Constraints:Must be a valid link ID

Pagination - 5 fieldsPagination Parameters

▼

---

Responses

200

Successful retrieval

Charges list retrieved successfully. Returns a paginated list of charge objects.

Response structure:

• object - Always returns "list"
• data - Array of charge objects associated with the link
• limit - Records per page
• offset - Number of records skipped
• total - Total number of charges for this link
• order - Sort order applied
• from - Start date filter applied
• to - End date filter applied

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Invalid date format (must be ISO 8601)
• Invalid limit value (exceeds maximum)
• Invalid order value
• Malformed parameters

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

404

Not found

Link not found with the provided ID.

Common causes:

• Invalid link ID format
• Link does not exist
• Link belongs to different account
• Using test key with live link ID (or vice versa)

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/links/link_test_5xuy4w91xqz7d1w9u0t/charges \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -G \
  -d "limit=20" \
  -d "offset=0" \
  -d "order=reverse_chronological"

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

link = Omise::Link.retrieve('link_test_5xuy4w91xqz7d1w9u0t')
charges = link.charges(
  limit: 20,
  offset: 0,
  order: 'reverse_chronological'
)

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

link = omise.Link.retrieve('link_test_5xuy4w91xqz7d1w9u0t')
charges = link.charges(
    limit=20,
    offset=0,
    order='reverse_chronological'
)

Node.js

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

const charges = await omise.links.listCharges('link_test_5xuy4w91xqz7d1w9u0t', {
  limit: 20,
  offset: 0,
  order: 'reverse_chronological'
});

PHP

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

$link = OmiseLink::retrieve('link_test_5xuy4w91xqz7d1w9u0t');
$charges = $link->charges([
    'limit' => 20,
    'offset' => 0,
    'order' => 'reverse_chronological'
]);

Java

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

ScopedList<Charge> charges = client.links()
    .get("link_test_5xuy4w91xqz7d1w9u0t")
    .charges()
    .list()
    .limit(20)
    .offset(0)
    .order(Ordering.ReverseChronological)
    .send();

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var charges = await client.Links.ListCharges("link_test_5xuy4w91xqz7d1w9u0t", new ListOptions
{
    Limit = 20,
    Offset = 0,
    Order = ListOrder.ReverseChronological
});

Go

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

charges, _ := client.Links().ListCharges("link_test_5xuy4w91xqz7d1w9u0t", &omise.ListParams{
    Limit:  20,
    Offset: 0,
    Order:  omise.ReverseChronological,
})

---

Error and result codes

Common Error Codes

Code	Description	Resolution
authentication_failure	Invalid API key	Verify your secret key is correct
not_found	Link not found	Check link ID is correct and exists
invalid_link_id	Malformed link ID	Ensure ID matches format link(test)?[0-9a-z]+
invalid_date_format	Date format validation failed	Use ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)

Charge Object Fields

Field	Type	Description
object	string	Always returns "charge"
id	string	Unique charge identifier
livemode	boolean	Production vs test environment indicator
amount	integer	Transaction value in smallest currency unit
currency	string	ISO currency code
status	string	Charge status (successful, failed, pending, etc.)
paid	boolean	Whether the charge has been paid
link	string	Associated link ID
created_at	string	Creation timestamp (ISO 8601)

---

🔑API Credentials

▼

Try it out

Required - 1 fields

▼

link_id(Required)

Additional - 5 fields

▼

Your IP: ...Loading...