Back to the reference

Payins

Retrieve incoming money for your merchant.

A payin is any incoming money for your merchant, whether it comes from a payment link or a deposit account. Every payin starts as pending and becomes settled only after Clobepay validates the payment. An expired or failed payin does not become settled on its own. Settlement is in USDT.

Payin statuses
pending
Payment validated
settled
Full refundrefunded
Expiredexpired
Failedfailed
GET

List payins

/api/v1/payins

Newest first. Scope payins:read.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

status
query
stringOptional

Filter by status.

pending · settled · expired · failed · refunded

source
query
stringOptional

Payin source.

payment_link · deposit_account · bank_transfer · crypto_deposit · internal_transfer

from
query
stringOptional

ISO-8601: createdAt ≥ from.

to
query
stringOptional

ISO-8601: createdAt ≤ to.

limit
query
numberOptional

1–100 (default 20).

startingAfter
query
stringOptional

Cursor: a public pi_… id from the previous page.

Responses

  • HTTP 200Cursor list.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 422invalid_statusstatus is not an allowed value.
  • HTTP 422invalid_sourcesource is not an allowed value.
  • HTTP 422invalid_fromfrom is not a valid ISO-8601 date.
  • HTTP 422invalid_toto is not a valid ISO-8601 date.
  • HTTP 422invalid_limitlimit is not an integer between 1 and 100.
  • HTTP 422invalid_cursorstartingAfter is not the id (pi_…) of a payin of your merchant.
GET/payins
curl -X GET "$CLOBEPAY_API_BASE/payins?status=pending&limit=10" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 200
{
  "object": "list",
  "data": [
    {
      "id": "pi_3Kx9mQ2vR8wL0tYbA4nC1e",
      "object": "payin",
      "status": "pending",
      "source": "payment_link",
      "amount": "50.00",
      "asset": "USDT",
      "providerFee": null,
      "netAmount": null,
      "paymentLinkId": "7c2e1a4b-9d83-4f21-a6b0-2e8c91f04d17",
      "providerReference": null,
      "settledAt": null,
      "availableAt": null,
      "refundedAt": null,
      "metadata": {
        "cart_id": "c_77"
      },
      "createdAt": "2026-11-19T18:00:00.000Z",
      "updatedAt": "2026-11-19T18:00:00.000Z"
    }
  ],
  "hasMore": false
}

GET

Retrieve a payin

/api/v1/payins/{payinId}

Detail by public pi_… id. Scope payins:read.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

payinId
path
stringRequired

Public id (pi_…).

Responses

  • HTTP 200Detail.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 404payin_not_foundIt does not exist or does not belong to your merchant.
GET/payins/{payinId}
curl -X GET "$CLOBEPAY_API_BASE/payins/pi_3Kx9mQ2vR8wL0tYbA4nC1e" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 200
{
  "id": "pi_3Kx9mQ2vR8wL0tYbA4nC1e",
  "object": "payin",
  "status": "settled",
  "source": "payment_link",
  "amount": "50.00",
  "asset": "USDT",
  "providerFee": null,
  "netAmount": null,
  "paymentLinkId": "7c2e1a4b-9d83-4f21-a6b0-2e8c91f04d17",
  "providerReference": null,
  "settledAt": "2026-11-19T18:05:00.000Z",
  "availableAt": "2026-11-19T18:05:00.000Z",
  "refundedAt": null,
  "metadata": {
    "cart_id": "c_77"
  },
  "createdAt": "2026-11-19T18:00:00.000Z",
  "updatedAt": "2026-11-19T18:00:00.000Z"
}