> ## Documentation Index
> Fetch the complete documentation index at: https://docs.accelebit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Payment — POST /v1/payments

> Submit a card payment through Accelebit. Accepts card details, billing info, and amount. Returns status, provider, and 3DS redirect data if required.

Use this endpoint to submit a card payment through Accelebit. You provide the card details, billing information, amount, and currency, and Accelebit routes the transaction to the optimal upstream provider based on currency and availability. The response tells you whether the payment was captured immediately, requires 3D Secure authentication, or failed.

<Note>
  Always supply a unique `Idempotency-Key` on every request. If a request is retried with the same key, Accelebit returns the original response without creating a duplicate payment.
</Note>

## Headers

<ParamField header="X-API-Key" type="string" required>
  Your secret API key. Starts with `smtgw_sk_`.
</ParamField>

<ParamField header="Idempotency-Key" type="string" required>
  A unique key to prevent duplicate payments. Use a UUID or an order-specific identifier.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Request body

<ParamField body="amount" type="string" required>
  Payment amount as a decimal string. For example: `"55.00"` or `"100.50"`. Maximum two decimal places.
</ParamField>

<ParamField body="currency" type="string" required>
  Three-letter ISO 4217 currency code. Automatically uppercased. For example: `"EUR"`, `"USD"`, `"GBP"`.
</ParamField>

<ParamField body="paymentMethod" type="string" default="card">
  Payment method type. One of `card` or `stored_card`.
</ParamField>

<ParamField body="customerId" type="string" required>
  Your external customer identifier. Used to resolve or create a customer record in Accelebit.
</ParamField>

<ParamField body="card" type="object">
  Card details. Required when `paymentMethod` is `card`.

  <Expandable title="card properties">
    <ParamField body="card.number" type="string" required>
      Card number (PAN). 13–19 digits.
    </ParamField>

    <ParamField body="card.expiryMonth" type="string" required>
      Two-digit expiry month. `"01"` through `"12"`.
    </ParamField>

    <ParamField body="card.expiryYear" type="string" required>
      Two-digit expiry year. For example: `"28"` for 2028.
    </ParamField>

    <ParamField body="card.cvv" type="string" required>
      Card verification value. 3–4 digits.
    </ParamField>

    <ParamField body="card.holderName" type="string" required>
      Name as printed on the card.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="storedCardId" type="string">
  UUID of a previously stored card. Required when `paymentMethod` is `stored_card`.
</ParamField>

<ParamField body="billing" type="object">
  Billing information for the cardholder.

  <Expandable title="billing properties">
    <ParamField body="billing.firstName" type="string">
      Cardholder's first name.
    </ParamField>

    <ParamField body="billing.lastName" type="string">
      Cardholder's last name.
    </ParamField>

    <ParamField body="billing.email" type="string" required>
      Cardholder's email address.
    </ParamField>

    <ParamField body="billing.phone" type="string" required>
      Phone number including country code. Minimum 5 characters. For example: `"+35699123456"`.
    </ParamField>

    <ParamField body="billing.country" type="string" required>
      ISO 3166-1 alpha-2 country code. Automatically uppercased. For example: `"MT"`, `"DE"`.
    </ParamField>

    <ParamField body="billing.address" type="string" required>
      Street address line 1.
    </ParamField>

    <ParamField body="billing.addressLine2" type="string">
      Street address line 2.
    </ParamField>

    <ParamField body="billing.city" type="string" required>
      City.
    </ParamField>

    <ParamField body="billing.postalCode" type="string" required>
      Postal or ZIP code.
    </ParamField>

    <ParamField body="billing.state" type="string">
      State or province. Required for US and CA addresses.
    </ParamField>

    <ParamField body="billing.ipAddress" type="string">
      Customer's IPv4 address. If omitted, Accelebit uses the IP from the incoming request.
    </ParamField>

    <ParamField body="billing.dob" type="string">
      Date of birth in `YYYY-MM-DD` format. Required by some providers (Everest).
    </ParamField>

    <ParamField body="billing.gender" type="string">
      `"M"` or `"F"`. Required by some providers (Everest).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="merchantRef" type="string">
  Your own reference ID, such as an order number. You can use this value to look up the payment later via `GET /v1/payments?merchantRef=...`.
</ParamField>

<ParamField body="returnUrl" type="string">
  URL to redirect the customer to after 3D Secure authentication completes. Required if your integration handles 3DS flows.
</ParamField>

<ParamField body="deviceFingerprint" type="string">
  Device fingerprint string. Maximum 128 characters. Passed to the upstream provider for fraud scoring.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs to attach to this payment. Stored by Accelebit but not forwarded to providers.
</ParamField>

## Response

<ResponseField name="data" type="object">
  <Expandable title="data properties">
    <ResponseField name="id" type="string">
      UUID of the created transaction.
    </ResponseField>

    <ResponseField name="status" type="string">
      Transaction status. One of: `captured`, `authorized`, `pending_3ds`, `failed`.
    </ResponseField>

    <ResponseField name="amount" type="string">
      Payment amount as a decimal string. Matches the value you submitted.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Three-letter ISO 4217 currency code.
    </ResponseField>

    <ResponseField name="provider" type="string">
      The upstream provider that processed the payment. For example: `"everest"`, `"triple000"`.
    </ResponseField>

    <ResponseField name="threeDsRequired" type="boolean">
      `true` if the customer must complete 3D Secure authentication before the payment can be captured.
    </ResponseField>

    <ResponseField name="threeDsData" type="object">
      3DS redirect data. `null` if 3DS is not required.

      <Expandable title="threeDsData properties">
        <ResponseField name="redirectUrl" type="string">
          URL to redirect the customer to for 3DS authentication.
        </ResponseField>

        <ResponseField name="method" type="string">
          HTTP method for the redirect. Either `"GET"` or `"POST"`.
        </ResponseField>

        <ResponseField name="parameters" type="object">
          Key-value pairs to submit alongside the redirect. Only populated for POST redirects.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of when the payment was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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_abc123" \
    -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"
    }'
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.gateway.accelebit.com/v1/payments', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.ACCELEBIT_SECRET_KEY!,
      'Idempotency-Key': `pay_${crypto.randomUUID()}`,
    },
    body: JSON.stringify({
      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',
    }),
  });

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests
  import uuid

  response = requests.post(
      'https://api.gateway.accelebit.com/v1/payments',
      headers={
          'Content-Type': 'application/json',
          'X-API-Key': ACCELEBIT_SECRET_KEY,
          'Idempotency-Key': f'pay_{uuid.uuid4()}',
      },
      json={
          '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',
      },
  )

  result = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 201 - Payment Captured theme={null}
  {
    "data": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "captured",
      "amount": "55.00",
      "currency": "EUR",
      "provider": "everest",
      "threeDsRequired": false,
      "threeDsData": null,
      "createdAt": "2026-04-09T12:01:00.000Z"
    }
  }
  ```

  ```json 201 - 3DS Required theme={null}
  {
    "data": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "pending_3ds",
      "amount": "55.00",
      "currency": "EUR",
      "provider": "everest",
      "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"
        }
      },
      "createdAt": "2026-04-09T12:01:00.000Z"
    }
  }
  ```

  ```json 400 - Validation Error theme={null}
  {
    "data": null,
    "error": {
      "status": 400,
      "name": "INVALID_REQUEST",
      "message": "Card details required for card payments"
    }
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "data": null,
    "error": {
      "status": 401,
      "name": "UNAUTHORIZED",
      "message": "Invalid or missing API key"
    }
  }
  ```
</ResponseExample>