Back to Home

The payment object

To receive funds from your customer, you must first create a payment. Payment is initially created with an unpaid status and a payment request that can be converted into a QR code. Your customer can pay the funds by scanning this QR code. When any amount of funds is transferred by the customer, the status of the payment changes to paid. Even if the payment made is partial, the status will change to paid. The payment object is marked expired when the timeframe (ttl) expires.

Speed now provides you with the option to split the payments you receive from your customers among several other existing Speed accounts. This eliminates the need to manually transfer funds to other accounts upon payment, and it also helps to simplify financial management. You need to define the following fields to do so:

  • Destination account: Enter the ID of the account to whom you want to transfer the defined percentage of the payment received. Make sure it is not your own account ID.
  • Percentage: Enter the percentage of the received payment that you want to send to the destination account. It should be greater than 0 and less than or equal to 100%.
    • The total of percentage of all the accounts (in case of multiple accounts) must be less than or equal to 100%
    • System to initiate the transfer after deducting Speed and other fees (as applicable, for example, affiliate partner fees).

ℹ️

Make sure you create and manage new payments upon receival of partial payment if you still want to collect further payment.

{
    "id": "pi_ll6ohfqq6V9HXSdv",
    "object": "payment",
    "status": "unpaid",
    "currency": "SATS",
    "amount": 5000,
    "exchange_rate": 1,
    "target_currency": "SATS",
    "target_amount": 5000,
    "target_amount_paid": null,
    "target_amount_paid_at": null,
    "ttl": 600,
    "expires_at": 1691764396466,
    "payment_request": "lntb50u1pjdv3z5psalzmyr55m57k3eu6pvdyy8t8vvun4tagl6jhbdsvsbhbb3cah2jbv7vecjthgq28np5w",
    "statement_descriptor": "Espresso",
    "description": "Payment V2",
    "transfers": [
        {
            "transfer_id": null,
            "destination_account": "acct_le6w3bimWMoctUVB",
            "percentage": 50.0,
            "fixed_amount": null,
            "created_type": "SHARE",
            "amount": null,
            "description": "tr-1"
        },
        {
            "transfer_id": null,
            "destination_account": "acct_le6w3bimWMoctUz",
            "percentage": 50.0,
            "fixed_amount": null,
            "created_type": "SHARE",
            "amount": null,
            "description": "tr-2"
        }
    ],
    "metadata": {
        "type": "internal",
        "no": "1"
    },
    "speed_fee": {
        "percentage": 0.0,
        "amount": null
    },
    "created": 1691763796466,
    "modified": 1691763796466
}

Attributes

id string
Unique identifier for the object.

object string
The type of the object indicates to which entity this response belongs.

status string
A payment object can have 4 statuses as mentioned below.

  • unpaid
  • The payment object has unpaid status after its generation until it is paid or expired.
  • paid
  • The payment object is marked paid once any amount (the amount may be less than the actual payment in the case of on-chain partial payment) of payment is received within the timeframe (ttl).
  • expired
    • If the payment is not received within the stipulated timeframe (ttl) then it will be marked as expired.
  • cancelled
  • When you deactivate a checkout or payment link, the payment associated with it gets cancelled.

currency string
The base currency in which you prefer to work.

amount BigDecimal
Total amount for which the payment was created. Values up to 32 digits can be handled by the amount param, which can have a decimal precision up to 16 digits.

exchange_rate BigDecimal
The exchange rate is used to convert the currency(base currency) into target_currency.

target_currency string
The cryptocurrency in which you want to receive payment from your customer. As of now, Speed only supports SATS and BTC.

target_amount BigDecimal
The converted amount (from base currency to target_currency) for which the payment request is generated.

target_amount_paid BigDecimal
Once the payment is made, this returns the exact amount received in the target_currency.

target_amount_paid_at timestamp
Time at which the payment was paid.

target_amount_paid_by string
This parameter specifies the id of the payment method through which this payment was made.

confirmations integer
This parameter specifies the number of confirmations received for the on-chain payment.

payment_methods enum
Both on-chain and lightning network methods can be used to receive funds. Please indicate whether you want to use lightning or on-chain. To ensure that you can receive both on-chain and lightning payments, remember to keep the “BTC On-chain” payment method enabled.

payment_method_options integer
This object contains two objects, lightning, and on-chain, both specifying all the data required to process the payment.

  • on_chain
  • This object has all the data associated with the payment if the payment method is on-chain.
    • id
    • Unique identifier for the on-chain object.
    • address
    • It specifies the BTC wallet address to which the payment is processed.
  • lightning
  • This object has all the data associated with the payment if the payment method is lightning.
    • id
    • Unique identifier for the lightning object.
    • payment_request
    • The lightning network payload for generating a QR code is returned.

transfers array of json
This array contains details about each transfer.

  • transfer_id
  • Unique identifier for the transfer. This has null value until the status for the payment updates to paid.
  • destination_account
  • It specifies the ID of the destination account to whom you want to transfer the funds once a payment is marked as paid.
  • percentage
  • It specifies the percentage of the payment received that you want to send to the destination account.
  • amount
  • It specifies the amount that is transferred to the destination account. This has null value until the status for the payment updates to paid.
  • description
  • It is additional information about the transfer.

onchain_tx_explorer_link string
Once the payment is made you can check the payment details on this mempool link.

expires_at timestamp
Time at which the payment expires.

description string
Additional information about this payment.

statement_descriptor string
Additional information about a payment made to an account. Default is “ Payment from <account_name> “ if you don’t pass any value.

transfers list
You may use this to trigger a transfer of funds to one or more existing Speed accounts when your customers pay you.

metadata object
You can use this to store additional information about the object in a structured format.

created timestamp
Time at which the payment object was created.

modified timestamp
Time at which the last modification was made.