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.
List payins
/api/v1/payins
Newest first. Scope payins:read.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
statusstringOptionalFilter by status.
pending · settled · expired · failed · refunded
sourcestringOptionalPayin source.
payment_link · deposit_account · bank_transfer · crypto_deposit · internal_transfer
fromstringOptionalISO-8601: createdAt ≥ from.
tostringOptionalISO-8601: createdAt ≤ to.
limitnumberOptional1–100 (default 20).
startingAfterstringOptionalCursor: a public pi_… id from the previous page.
Responses
- HTTP 200Cursor list.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 422
invalid_statusstatus is not an allowed value. - HTTP 422
invalid_sourcesource is not an allowed value. - HTTP 422
invalid_fromfrom is not a valid ISO-8601 date. - HTTP 422
invalid_toto is not a valid ISO-8601 date. - HTTP 422
invalid_limitlimit is not an integer between 1 and 100. - HTTP 422
invalid_cursorstartingAfter is not the id (pi_…) of a payin of your merchant.
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
}Retrieve a payin
/api/v1/payins/{payinId}
Detail by public pi_… id. Scope payins:read.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
payinIdstringRequiredPublic id (pi_…).
Responses
- HTTP 200Detail.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 404
payin_not_foundIt does not exist or does not belong to your merchant.
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"
}