Payment Requests

Payment Requests provide the ability to generate dynamic payment requests, with either a checkout system or return raw payment details to build your own white-label checkout.

Types of Payment Requests

Selly currently supports two types of payment request options:

White-label

When the white_label attribute is set to true, the Payment Requests API endpoint returns a subset of the Order object allowing you to build a custom checkout experience using the raw order properties, as well as providing live updates toy our customers through webhooks.

integrated

With the integrated option, the Payment Requests API endpoint returns a url that you should redirect your customer to. This URL provides a fully integrated checkout experience, and upon completion of the payment, the customer will be redirected to the provided return_url.

POST/v2/payment_requests

Create a white-label payment request

This endpoint allows you to create a white-label payment request.

Name
white_label
Type
boolean
required
Description
Set to true to return a white-label payment request.
Name
title
Type
string
required
Description
Displayed title of the payment request.
Name
email
Type
string
required
Description
Customer's email address.
Name
value
Type
float
required
Description
Value/price of the payment in the currency specified.
Name
currency
Type
string
required
Description
The ISO 4217 currency code used for this payment.
Name
payment_gateway
Type
enum
required
Description
Available payment gateways are:
- paypal
- stripe
- cashapp
- bitcoin
- ethereum
- litecoin
- bitcoin_cash
- perfect_money
- skrill
- dogecoin
- bnb
- polygon
Name
ip_address
Type
string
required
Description
The customer's IP address.
Name
crypto_required_confirmations
Type
integer
Description
Required cryptocurrency confirmations to have a payment considered complete. Defaults to the values set in global cryptocurrency confirmations required settings in your payments settings.
Name
metadata
Type
object
Description
Object of key/value for extra metadata to store in the payment and order. E.g, customer/user ID

Request

POST

/api/v2/payment_requests

curl -X POST https://selly.io/api/v2/payment_requests \
  -H "Authorization: Bearer {token}" \
  -d title="Invoice #12387" \
  -d white_label=true \
  -d return_url="https://yoursite.com/return" \
  -d ip_address="86.241.31.12" \
  -d payment_gateway="paypal" \
  -d value="10.00" \
  -d currency="USD" \
  -d metadata[custom_id]="12345" \

Response

{
  "id": "83c82a84-b20d-470b-b3a7-c276c68a4507",
  "product_id": "pay",
  "email": "customer@example.com",
  "value": "10.0",
  "quantity": 1,
  "currency": "USD",
  "payment_gateway": "paypal",
  "status": 0,
  "amounts": {
    "AED": 36.72,
    "ARS": 8086.44,
    "AUD": 14.68,
    "AZN": 17.01,
    "BRL": 48.51,
    "CAD": 13.25,
    "CHF": 8.41,
    "CNY": 70.99,
    "CRC": 5315.98,
    "CZK": 223.12,
    "DKK": 67.5,
    "EUR": 9.06,
    "GBP": 7.85,
    "HKD": 78.08,
    "HUF": 3464.99,
    "ILS": 36.24,
    "INR": 831.71,
    "ISK": 1374.6,
    "JPY": 1409.89,
    "KRW": 12934.46,
    "MXN": 169.62,
    "MYR": 45.89,
    "NGN": 8816.56,
    "NOK": 101.61,
    "NZD": 15.82,
    "PHP": 553.87,
    "PKR": 2792.0,
    "PLN": 39.31,
    "QAR": 36.41,
    "RON": 45.05,
    "RUB": 893.87,
    "SAR": 37.45,
    "SEK": 100.77,
    "SGD": 13.2,
    "THB": 343.71,
    "TRY": 295.07,
    "TWD": 321.84,
    "USD": 10.0,
    "ZAR": 194.6
  },
  "exchange_rates": {
    "AED": 3.672,
    "ARS": 808.644,
    "AUD": 1.468,
    "AZN": 1.701,
    "BRL": 4.851,
    "CAD": 1.325,
    "CHF": 0.841,
    "CNY": 7.099,
    "CRC": 531.598,
    "CZK": 22.312,
    "DKK": 6.75,
    "EUR": 0.906,
    "GBP": 0.785,
    "HKD": 7.808,
    "HUF": 346.499,
    "ILS": 3.624,
    "INR": 83.171,
    "ISK": 137.46,
    "JPY": 140.989,
    "KRW": 1293.446,
    "MXN": 16.962,
    "MYR": 4.589,
    "NGN": 881.656,
    "NOK": 10.161,
    "NZD": 1.582,
    "PHP": 55.387,
    "PKR": 279.2,
    "PLN": 3.931,
    "QAR": 3.641,
    "RON": 4.505,
    "RUB": 89.387,
    "SAR": 3.745,
    "SEK": 10.077,
    "SGD": 1.32,
    "THB": 34.371,
    "TRY": 29.507,
    "TWD": 32.184,
    "USD": 1.0,
    "ZAR": 19.46
  },
  "product_type": "payment_request",
  "crypto_exchange_rates": null,
  "crypto_address": null,
  "crypto_channel": null,
  "crypto_value": null,
  "crypto_received": null,
  "crypto_confirmations": null,
  "crypto_required_confirmations": 0,
  "payment_request": {
    "id": "1741190769068490753",
    "title": "Invoice #12387"
  },
  "redirect_url": null,
  "tax_inclusivity": "exclusive",
  "tax_rate": "0.0",
  "tax_amount": "0.0",
  "expires_at": null,
  "created_at": "2023-12-30T20:13:26.000+00:00",
  "updated_at": "2023-12-30T20:13:26.000+00:00",
  "payment_redirection_url": "https://www.paypal.com/checkoutnow?token=1UX524656F788150S"
}

POST/v2/payment_requests

Create an integrated payment request

This endpoint allows you to create a payment request that returns a URL to an integrated Selly-hosted checkout page.

Name
title
Type
string
required
Description
Displayed title of the payment request.
Name
email
Type
string
required
Description
Customer's email address.
Name
value
Type
float
required
Description
Value/price of the payment in the currency specified.
Name
currency
Type
string
required
Description
The ISO 4217 currency code used for this payment.
Name
payment_gateway
Type
enum
required
Description
Available payment gateways are:
- paypal
- stripe
- cashapp
- bitcoin
- ethereum
- litecoin
- bitcoin_cash
- perfect_money
- skrill
- dogecoin
- bnb
- polygon
Name
return_url
Type
string
required
Description
The URL the customer is returned/redirected to after successful payment.
Name
crypto_required_confirmations
Type
integer
Description
Required cryptocurrency confirmations to have a payment considered complete. Defaults to the values set in global cryptocurrency confirmations required settings in your payments settings.
Name
metadata
Type
object
Description
Object of key/value for extra metadata to store in the payment and order. E.g, customer/user ID

Request

POST

/api/v2/payment_requests

curl -X POST https://selly.io/api/v2/payment_requests \
  -H "Authorization: Bearer {token}" \
  -d title="Invoice #12387" \
  -d return_url="https://yoursite.com/return" \
  -d ip_address="86.241.31.12" \
  -d payment_gateway="paypal" \
  -d value="10.00" \
  -d currency="USD" \
  -d metadata[custom_id]="12345" \

Response

{
  "url": "https://selly.io/payment_requests/1422683412963033089/1740673176096083919/PDCdKkyurZKpjgDlmQt9FCoh4WxnniDfxaGedZsw=="
}