Payment Modes & Integration

The Swiftspace API offers flexible payment integration options designed to suit your business needs. This guide covers authentication, payment modes, and webhooks.

Authentication

All API requests must be authenticated using your API key. Include it in the Authorization header of your requests with the Bearer scheme:

Authorization: Bearer <YOUR_API_KEY>

You can obtain your API key from the Swiftspace Dashboard.

---

1. Multi-Provider Mode

Best for: Maximizing conversion rates by offering customers a choice of payment methods.

In this mode, you omit the provider field. The user is redirected to a Swiftspace-hosted checkout page where they can select their preferred payment provider (e.g., Mercuryo, Stripe, MoonPay).

Try it out

Create Payment

POST

/payment

Initialize a payment session. Choose between Multi-Provider Mode (default) or Single-Provider Mode by setting the provider field.

Authorizations

bearerAuth

TypeHTTP (bearer)

Request Body

application/json

{

"amount": 0,

"email": "string",

"currency": "string",

"webhook": "string",

"redirect_url": "string",

"provider": "string"

}

Responses

Payment created successfully

Content-Type

application/json

{

"id": "string",

"amount": 0,

"email": "string",

"currency": "string",

"status": "string",

"created_on": "string",

"payment_link": "string",

"provider": "string"

}

POST

/payment

Playground

Authorization

bearerAuth

Body

Samples

Powered by VitePress OpenAPI

Code Example

cURL

curl -X POST https://app.swiftspace.co/api/v1/payment \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d 
'{'
    "amount": 100.00,
    "currency": "USD",
    "email": "customer@example.com",
    "webhook": "https://your-site.com/webhook"
  }'

JavaScript

const response = await fetch("https://app.swiftspace.co/api/v1/payment", {
    method: "POST",
    headers: {
        "Authorization": "Bearer <YOUR_API_KEY>",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        amount: 100.0,
        currency: "USD",
        email: "customer@example.com",
        webhook: "https://your-site.com/webhook",
    }),
});
const data = await response.json();

---

2. Single-Provider Mode

Best for: White-label experiences or when you need to enforce specific provider rules.

Specify a provider in your request (e.g., stripe, mercuryo). This locks the payment to that provider and strictly validates the currency and amount against that provider's limits before creating the transaction.

Supported Providers

mercuryo, guardarian, utorg, coinbase, alchemypay, stripe, and more (see API Schema).

Code Example

cURL

curl -X POST https://app.swiftspace.co/api/v1/payment \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d 
'{'
    "amount": 100.00,
    "currency": "USD",
    "email": "customer@example.com",
    "webhook": "https://your-site.com/webhook",
    "provider": "stripe"
  }'

---

Webhooks

We send real-time updates to your server whenever a payment status changes (e.g., from Invoice Created to Paid). Provide your endpoint in the webhook field when creating a payment.

Payload Example

The webhook sends a POST request with the following JSON payload:

{
  "success": true,
  "status": "Paid",
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 107.0,
  "currency": "USD",
  "provider": "stripe",
  "email": "customer@example.com",
  "redirect_url": "https://your-site.com/success",
  "paid_on": "2024-02-12T10:30:45.123456",
  "value_coin": null,
  "coin": null,
  "txid_in": null,
  "txid_out": null
}

Security: Verify that the webhook is legitimate by checking your server logs for the transaction ID or implementing a secret token check in your webhook URL parameters (e.g., ?secret=my_secret).