Charges

Create a charge

A payment request in your own currency. Send the customer to its hosted_url; they choose a coin and pay, and you get a charge:confirmed webhook.

POST/v1/charges

Payment gateway

Create a charge

curl --request POST \
  --url 'http://localhost:4188/api/v1/charges' \
  --header "X-Api-Key: $RIMOSWAP_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Order #1042",
    "description": "2x Blue T-Shirt (L)",
    "amount": 25,
    "currency": "USD",
    "metadata": {
      "order_id": "1042"
    },
    "redirect_url": "https://yourstore.com/thanks",
    "cancel_url": "https://yourstore.com/cart"
  }'

201Response

{
  "charge": {
    "code": "F3ADAB39B66D",
    "name": "Order #1042",
    "description": "2x Blue T-Shirt (L)",
    "local_amount": 25,
    "local_currency": "USD",
    "coin": null,
    "chain": "tron",
    "crypto_amount": null,
    "status": "new",
    "cancellable": true,
    "merchant_name": "Sellr",
    "merchant_tag": "sellr",
    "expires_at": "2026-10-25 17:47:39",
    "expires_in": 3600,
    "payment_expires_in": 1200,
    "hosted_url": "https://rimoswap.com/c/F3ADAB39B66D",
    "redirect_url": "https://yourstore.com/thanks",
    "cancel_url": "https://yourstore.com/cart",
    "metadata": {
      "order_id": "1042"
    },
    "test": false
  }
}

Authorizations

X-Api-Keystringheaderrequired
Your API key. Test keys start rmo_test_, live keys rmo_live_.

Body

application/json

namestringrequired
Shown on the checkout, e.g. the order number.
Example: "Order #1042"
amountnumberrequired
In your currency, up to two decimal places.
Example: "25.00"
currencystringdefault: USD
Your currency.
Options: USD, NGN
descriptionstring
A line under the name, up to 255 characters.
Example: "2x Blue T-Shirt (L)"
metadataobject
Anything you need back: it is returned untouched on every webhook. Put your order id here.
redirect_urlstring
Where to send the customer after paying. Not proof of payment: wait for the webhook.
Example: "https://yourstore.com/thanks"
cancel_urlstring
Where the checkout’s cancel button goes.
Example: "https://yourstore.com/cart"

Good to know

The crypto amount is locked against your price for 20 minutes once the customer picks a coin. The charge itself expires after an hour.
A test key makes a test charge: the same checkout, marked Test mode, settled with the simulate endpoint.
Customers with a Rimoswap account pay from their balance instantly, with no network fee.

Webhooks

Sends charge:created, charge:confirmed, charge:expired, charge:cancelled to the key's webhook URL. Verifying them.

Errors

403 gateway_disabledThe payment gateway has been switched off for your business. Test keys still work.
403 kyc_requiredLive keys need business verification.
422 —A field failed validation; the message says which.