Payments
Use the endpoint below to create a new payment.
When a new payment is created, the "Created" status is assigned to it.
Once the payemnt is created, the backend begins tracking incoming payments on the blockchain
and updates the status and other attributes accordingly.
The following statuses could be assigned to an payment:
| Status | Description |
|---|---|
| Created | Initial status for new payments |
| InProgress | The payment is processing |
| Succeeded | The payment was successfully processed on the blockchain |
| Failed | The payment failed due to an error |
| Expired | The payment is expired and can no longer be processed |
Create a payment
Create a new payment returning its identifier
Learn about authenticationRequired attributes
- Name
amount- Type
- object
- Description
Amount in tokens, e.g {"value": "15.00", "currency": "btUSDTv2"}.
- Name
expiresAt- Type
- string
- Description
Date/time when payment expires (in ISO 8601 format).
Optional attributes
- Name
metadata- Type
- object
- Description
Extra metadata to be passed with events related to this payment.
Error codes
If something goes wrong during the processing of this request the error code in standard format is returned.
Request
curl --request POST \
--url https://api.smartypay.io/integration/payments \
--user API_KEY:SECRET \
--header 'content-type: application/json' \
--data '{
"amount": {
"value": "15",
"currency": "btUSDTv2"
},
"expiresAt": "2025-07-29T13:51:34.755Z"
}'
Response
{
"payment": {
"id": "3f4pZP9dwUGDUbtVRXrjDh",
"amount": {
"value": "15",
"currency": "btUSDTv2"
},
"status": "Created",
"createdAt": "2024-07-29T13:01:25.752997Z",
"expiresAt": "2025-07-29T13:51:34.755Z",
//...
}
}
You can get payment details and status using the method below.
Get payment
Returns the payment details by id.
Required path params
- Name
id- Type
- string
- Description
Payment Id
Request
curl https://api.smartypay.io/integration/payments/3f4pZP9dwUGDUbtVRXrjDh
Response
{
"payment": {
"id": "3f4pZP9dwUGDUbtVRXrjDh",
"amount": {
"value": "15",
"currency": "btUSDTv2"
},
"status": "Created",
"createdAt": "2024-07-29T13:01:25.752997Z",
"expiresAt": "2025-07-29T13:51:34.755Z",
//...
}
}
Error codes
In case of error, you will receive the standard error object as a response with the following possible error codes. Use this code to handle them in an appropriate way.
The error codes listed below are only related to one-times payments; some generic errors might be also returned.
| Code | HTTP Code | Description |
|---|---|---|
| PaymentExpiresAtInvalid | 400 | The payment expiresAt date has invalid format or refers to the point in the past |
| PaymentAmountInvalid | 400 | The payment amount cannot be parsed due to the value or currency type |
| PaymentAmountNotSupported | 400 | Provided token code is not known or the network is disabled by a merchant |
| PaymentNotFound | 404 | Payment not found |
| MerchantNotFound | 400 | The merchant that provided in merchantId attribute is not found |
| PaymentMetadataSizeExceeded | 400 | Metadata JSON is too big, the maximum allowed size is 4Kb |
| PaymentDescriptionSizeExceeded | 400 | Description is too big, the maximum allowed size is 1Kb |