Swipe Payments API

Authentication

The Swipe API uses API keys to authenticate requests. You can view and manage your keys in the Swipe Dashboard. Test-mode keys have the prefix sk_test_ and live-mode keys have the prefix sk_live_.

Authentication is performed via HTTP Bearer auth. Provide your secret key as the bearer token value. All API requests must be made over HTTPS.

curl https://api.swipe.inc/v1/payments \
  -H "Authorization: Bearer sk_test_51H8xQ2eZvKYlo2C" \
  -H "Content-Type: application/json"

Making requests

The API accepts request bodies as JSON or form-encoded data. For requests that create or update resources, pass an Idempotency-Key header to safely retry without accidentally performing the same operation twice.

• Timestamps are returned in Unix epoch seconds unless otherwise noted.
• All amounts are represented in the smallest currency unit (e.g. cents, sen).
• Pagination is cursor-based via the starting_after and limit parameters.

Errors

Swipe uses conventional HTTP response codes to indicate the success or failure of a request. Codes in the 2xx range indicate success, 4xx codes indicate a client error, and 5xx codes indicate a server error.

Rate limits

The API allows up to 100 requests per second in live mode and 25 requests per second in test mode. If you exceed the limit, requests return a 429 Too Many Requests response. Every response includes X-RateLimit-Remaining and X-RateLimit-Reset headers.

The Payment object

Represents a single payment intent — the full lifecycle of collecting money from a customer. Below are the attributes returned on every payment resource.

{
  "id": "pay_3MtwBwLkdIwHu7ix",
  "object": "payment",
  "amount": 2500,
  "currency": "idr",
  "status": "succeeded",
  "created": 1719763200,
  "metadata": {
    "order_id": "6735"
  }
}

Create a payment

Creates a new payment. Once created, you can confirm it to attempt to move money from the customer's payment method to your Swipe balance.

Parameters

curl https://api.swipe.inc/v1/payments \
  -u sk_test_51H8xQ2: \
  -d amount=2500 \
  -d currency=idr \
  -d payment_method=pm_card_visa

{
  "id": "pay_3MtwBwLkdIwHu7ix",
  "amount": 2500,
  "currency": "idr",
  "status": "succeeded"
}

Retrieve a payment

Retrieves the details of a payment that has previously been created. Supply the unique payment ID returned from your create request.

curl https://api.swipe.inc/v1/payments/pay_3MtwBwLkdIwHu7ix \
  -u sk_test_51H8xQ2:

List payments

Returns a list of payments you've previously created. The payments are returned in sorted order, with the most recent appearing first. Use the limit and starting_after parameters to paginate.

Refund a payment

Refunds a payment that has previously been created but not yet refunded. Funds are refunded to the original payment method. You can refund the full amount or issue a partial refund by specifying an amount.

Webhooks

Webhooks let your application receive real-time notifications when events happen in your account — such as a payment succeeding or a refund completing. Configure endpoint URLs in your Dashboard and verify each event with the signature in the Swipe-Signature header.

SDKs & libraries

Official client libraries wrap the Swipe API so you can integrate quickly in your language of choice.