Logo

SMARTy Docs

Payments

The API allows you to create one-time payments, as well search for payments using filters and receive information for a single payment.

Guide: One-time payments

The Payment object

The Payment object includes all relevant details about a payment. It is created when a payment is initiated and is returned in response to any payment-related requests. This object might contain parameters and values not documented in the API Reference, which should be disregarded.

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the payment.

  • Name
    amount
    Type
    money
    Description

    The amount of money requested.

  • Name
    status
    Type
    string
    Description

    The status of this payment.

  • Name
    createdAt
    Type
    string
    Description

    ISO8601 Timestamp of when the payment was created.

  • Name
    expiresAt
    Type
    string
    Description

    ISO8601 Timestamp of when the payment expires.

  • Name
    metadata
    Type
    object
    Description

    Extra metadata as key-value data to be passed with events related to this payment.

  • Name
    description
    Type
    string
    Description

    Description of the payment.

  • Name
    errorCode
    Type
    string
    Description

    Use this code to find out the reason of the error occured when proccessing this payment.

POST/v1/payments

Create a payment

This endpoint allows you to create a new payment.

Learn about payment lifecycle

Required attributes

  • Name
    merchantId
    Type
    string
    Description

    The identifier of the merchant this payment is related to.

  • Name
    amount
    Type
    money
    Description

    The amount of payment requested.

Optional attributes

  • Name
    expiresAt
    Type
    string
    Description

    Timestamp of when the payment will expire.

  • Name
    metadata
    Type
    object
    Description

    Extra metadata to be passed with events related to this payment.

  • Name
    description
    Type
    string
    Description

    Description of the payment.

Error codes

If something goes wrong during the processing of this request the error code in standard format is returned.

See error codes

Request

POST
/v1/payments
curl --request POST \
  --url https://partner-api.smartypay.io/v1/payments \
  --user API_KEY:SECRET \
  --header 'content-type: application/json' \
  --data '{
    "amount": {
        "value": "15",
        "currency": "bUSDT"
    },
    "merchantId": "RgFw2p65CQn3pE8uriL53d"
}'

Response

{
    "id": "wv7xbaSP4ljdITbrFI995v",
    "amount": {
        "value": "15",
        "currency": "bUSDT"
    },
    "createdAt": "2021-06-21T14:44:58Z",
    "expiresAt": "2021-06-22T20:19:38Z",
    "status": "Created"
}
POST/v1/payments/search

Search for payments

This endpoint allows you to retrieve a paginated list of payments that optionally can be filtered based on the predicates defined below.

Predicates are combined with AND semantics.

Read more about pagination

Optional attributes

  • Name
    page
    Type
    object
    Description

    Defines pagination and sorting options.

  • Name
    predicates.statusIn
    Type
    array
    Description

    List of payment statuses to include in the response.

  • Name
    predicates.idIn
    Type
    array
    Description

    List of payment identifiers to include in the response.

Request

POST
/v1/payments/search
curl --request POST \
  --url https://partner-api.smartypay.io/v1/payments/search \
  --user API_KEY:SECRET \
  --header 'content-type: application/json' \
  --data '{
    "predicates": {
        "statusIn": [
            "Created",
            "InProgress"
        ],
        "merchantId": "RgFw2p65CQn3pE8uriL53d"
    },
    "page": {
        "limit": 5
    }
}'

Response

{
    "list": [
        {
            "id": "wv7xbaSP4ljdITbrFI995v",
            "amount": {
                "value": "15",
                "currency": "bUSDT"
            },
            "createdAt": "2021-06-21T14:44:58Z",
            "expiresAt": "2021-06-22T20:19:38Z",
            "status": "Created",
            "metadata": {
                "orderId": 1002112
            }
        },
        {
            "id": "rFI995vUhSIhXBhNe8Xv7x"
            // ...
        }
    ],
    "page": {
        "limit": 5,
        "offset": 0
    },
}
GET/v1/payments/{paymentId}

Retrieve a payment

This endpoint allows you to retrieve a payment by providing their unique id. Refer to the list at the top of this page to see which properties are included with payment objects.

Request

GET
/v1/payments/{paymentId}
curl https://partner-api.smartypay.io/v1/payments/wv7xbaSP4ljdITbrFI995v \
  --user API_KEY:SECRET

Response

{
    "id": "wv7xbaSP4ljdITbrFI995v",
    "amount": {
        "value": "15",
        "currency": "bUSDT"
    },
    "createdAt": "2021-06-21T14:44:58Z",
    "expiresAt": "2021-06-22T20:19:38Z",
    "status": "Succeeded",
    "metadata": {
        "orderId": 1002112
    }
}

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.

CodeHTTP CodeDescription
PaymentExpiresAtInvalid400The payment expiresAt date has invalid format or refers to the point in the past
PaymentAmountInvalid400The invoice amount cannot be parsed due to the value or currency type
PaymentAmountNotSupported400Provided token code is not known or the network is disabled by a merchant
PaymentNotFound404Payment not found
MerchantNotFound400The merchant that provided in merchantId attribute is not found
PaymentMetadataSizeExceeded400Metadata JSON is too big, the maximum allowed size is 4Kb
PaymentDescriptionSizeExceeded400Description is too big, the maximum allowed size is 1Kb
InvoiceInconsistentAsset400Aux amounts attribute has token codes from the different networks
InvoiceDuplicateAmounts400Aux amounts has duplicates values
CompensationDisabled400The gas compensation feature is disabled by a merchant