Skip to main content
Accelebit is a server-to-server payment API. Your backend collects card details from the customer, sends them directly to the Accelebit API over HTTPS, and handles the response—no redirects to hosted payment pages. This guide walks through the full payment flow, including 3D Secure handling, error management, and idempotency best practices.

​
Payment flow

The diagram below shows the end-to-end flow for a card payment, including the 3D Secure branch.

​
Create a payment

Send card details and billing information to POST /v1/payments. Amounts must be decimal strings (for example, "55.00"). Include an Idempotency-Key header on every request—see Idempotency for details. 
curl -X POST https://api.gateway.accelebit.com/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-API-Key: smtgw_sk_test_your_secret_key" \
  -H "Idempotency-Key: pay_unique_id_123" \
  -d '{
    "amount": "55.00",
    "currency": "EUR",
    "paymentMethod": "card",
    "customerId": "user_12345",
    "card": {
      "number": "4111111111111111",
      "expiryMonth": "12",
      "expiryYear": "28",
      "cvv": "123",
      "holderName": "Jane Doe"
    },
    "billing": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane@example.com",
      "phone": "+35699123456",
      "country": "MT",
      "address": "123 Main Street",
      "city": "Valletta",
      "postalCode": "VLT 1000"
    },
    "returnUrl": "https://yoursite.com/payment/callback",
    "merchantRef": "order_98765"
  }'

​
Response handling

A successful request returns a data object with a status field. Check this field to determine what to do next.
StatusMeaning
capturedPayment completed successfully. Funds will be settled.
authorizedPayment authorized but not yet captured (rare for direct integrations).
pending_3ds3D Secure authentication required. Redirect the customer.
failedPayment was declined or an error occurred.

​
3D Secure

When a payment requires 3D Secure, the API response includes threeDsRequired: true alongside a threeDsData object containing the redirect URL and any POST parameters needed to initiate the challenge. 
{
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "pending_3ds",
    "threeDsRequired": true,
    "threeDsData": {
      "redirectUrl": "https://provider.com/3ds/challenge?id=abc123",
      "method": "POST",
      "parameters": {
        "PaReq": "base64encodeddata...",
        "TermUrl": "https://api.gateway.accelebit.com/v1/3ds/callback/abc123"
      }
    }
  }
}
Handle 3DS with the following steps:
1

Redirect the customer

Send the customer’s browser to threeDsData.redirectUrl. If the method is POST, submit a form to that URL with the provided parameters.
2

Customer completes the challenge

The customer authenticates with their bank through the 3DS challenge page.
3

Bank redirects back to your returnUrl

After the challenge, the bank redirects the customer to the returnUrl you specified in the original payment request.
4

Accelebit sends a webhook

Accelebit delivers a payment.captured or payment.failed webhook to your server with the final payment status.
5

Confirm the status server-side

Call GET /v1/payments/:id to verify the payment status before fulfilling the order.
Never fulfill an order based on the returnUrl redirect alone. The customer can manipulate URL parameters. Always verify the payment status server-side via the API or a webhook before marking an order as paid.

​
Error handling

When a payment fails, the API returns an error object alongside a null data field. Read error.name to identify the failure reason and decide whether to retry or surface an error to the customer. 
{
  "data": null,
  "error": {
    "status": 400,
    "name": "CARD_DECLINED",
    "message": "The card was declined by the issuing bank"
  }
}
Error codeDescription
CARD_DECLINEDThe card was declined by the issuer.
PROVIDER_ERRORThe upstream provider returned an error. A retry may succeed.
INVALID_REQUESTThe request body is missing required fields or contains invalid values.
UNAUTHORIZEDThe API key is invalid or missing.
DUPLICATE_REQUESTThe idempotency key was already used with different request parameters.

​
Idempotency

Include an Idempotency-Key header on every POST request. If a network failure causes you to retry a request with the same key, the API returns the original response without creating a duplicate payment. 
-H "Idempotency-Key: pay_unique_id_123"
Follow these practices to get the most out of idempotency keys:
  • Use a UUID or a composite key like order_{orderId}_attempt_{n}.
  • Store the idempotency key alongside your order record so you can retry safely.
  • Note that keys expire after 24 hours.

​
Merchant reference

Use the merchantRef field to attach your own order or invoice ID to a payment. This lets you correlate Accelebit transactions with your internal records and look up payments without storing Accelebit’s transaction ID separately. 
curl "https://api.gateway.accelebit.com/v1/payments?merchantRef=order_98765" \
  -H "X-API-Key: smtgw_sk_test_your_secret_key"