Card payments and 3DS

This page covers accepting a card payment and handling 3D Secure (3DS) authentication. If you haven’t taken a payment yet, start with the quickstart guide.

An API key and a profile_id from the dashboard. Card acceptance must be enabled on your business profile.

Create the 3DS payment

Create and confirm the payment in one call. Set authentication_type to three_ds to require 3D Secure, and pass a return_url — the bank sends the customer back there after the challenge.Replace card_number, card_exp_month, card_exp_year, card_holder_name, and card_cvc below with your own card data. The values shown are illustrative only and are not test credentials.

curl --request POST \
  --url https://api.sandbox.pesaswap.io/payments \
  --header 'api-key: {{api_key}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 100,
    "currency": "KES",
    "confirm": true,
    "customer_id": "{{customer_id}}",
    "profile_id": "{{profile_id}}",
    "payment_method": "card",
    "payment_method_type": "debit",
    "authentication_type": "three_ds",
    "return_url": "https://example.com/payments/return",
    "payment_method_data": {
      "card": {
        "card_number": "4242 4242 4242 4242",
        "card_exp_month": "12",
        "card_exp_year": "28",
        "card_holder_name": "Jane Doe",
        "card_cvc": "123"
      }
    }
  }'

const response = await fetch("https://api.sandbox.pesaswap.io/payments", {
  method: "POST",
  headers: {
    "api-key": "{{api_key}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 100,
    currency: "KES",
    confirm: true,
    customer_id: "{{customer_id}}",
    profile_id: "{{profile_id}}",
    payment_method: "card",
    payment_method_type: "debit",
    authentication_type: "three_ds",
    return_url: "https://example.com/payments/return",
    payment_method_data: {
      card: {
        card_number: "4242 4242 4242 4242",
        card_exp_month: "12",
        card_exp_year: "28",
        card_holder_name: "Jane Doe",
        card_cvc: "123",
      },
    },
  }),
});

const payment = await response.json();
console.log(payment);

import requests

response = requests.post(
    "https://api.sandbox.pesaswap.io/payments",
    headers={
        "api-key": "{{api_key}}",
        "Content-Type": "application/json",
    },
    json={
        "amount": 100,
        "currency": "KES",
        "confirm": True,
        "customer_id": "{{customer_id}}",
        "profile_id": "{{profile_id}}",
        "payment_method": "card",
        "payment_method_type": "debit",
        "authentication_type": "three_ds",
        "return_url": "https://example.com/payments/return",
        "payment_method_data": {
            "card": {
                "card_number": "4242 4242 4242 4242",
                "card_exp_month": "12",
                "card_exp_year": "28",
                "card_holder_name": "Jane Doe",
                "card_cvc": "123",
            }
        },
    },
)

payment = response.json()
print(payment)

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.sandbox.pesaswap.io/payments",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "api-key: {{api_key}}",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "amount" => 100,
        "currency" => "KES",
        "confirm" => true,
        "customer_id" => "{{customer_id}}",
        "profile_id" => "{{profile_id}}",
        "payment_method" => "card",
        "payment_method_type" => "debit",
        "authentication_type" => "three_ds",
        "return_url" => "https://example.com/payments/return",
        "payment_method_data" => [
            "card" => [
                "card_number" => "4242 4242 4242 4242",
                "card_exp_month" => "12",
                "card_exp_year" => "28",
                "card_holder_name" => "Jane Doe",
                "card_cvc" => "123",
            ],
        ],
    ]),
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

The response comes back with status: "requires_customer_action" and a next_action object of type redirect_to_url — a successful call does not mean the payment is done:

{
  "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "status": "requires_customer_action",
  "amount": 100,
  "currency": "KES",
  "next_action": {
    "type": "redirect_to_url",
    "redirect_to_url": "https://sandbox.pesaswap.io/3ds/redirect/pay_mbabizu24mvu3mela5njyhpit4"
  }
}

Redirect the customer

Read next_action.redirect_to_url from the response.
Redirect the customer’s browser to that URL. The issuing bank runs its 3DS challenge there (OTP, banking app approval, etc).
When the challenge finishes, the bank redirects the customer back to the return_url you supplied.

With authentication_type: "no_three_ds", there is no redirect step. The payment can go straight to succeeded (or failed) in the same confirm call or shortly after, depending on the connector.

Poll for the final status

Once the customer returns to your return_url, fetch the authoritative status from the connector before treating the payment as complete.

The hit on your return_url is not proof that the payment succeeded. It only tells you the customer’s browser came back — the bank may still be finalizing the authentication, or the challenge may have failed. Never mark an order as paid at this point.Always call GET /payments/{payment_id}?force_sync=true after the redirect to fetch the authoritative status from the connector before you treat the payment as complete.

curl --request GET \
  --url 'https://api.sandbox.pesaswap.io/payments/pay_mbabizu24mvu3mela5njyhpit4?force_sync=true' \
  --header 'api-key: {{api_key}}'

const response = await fetch(
  "https://api.sandbox.pesaswap.io/payments/pay_mbabizu24mvu3mela5njyhpit4?force_sync=true",
  {
    method: "GET",
    headers: { "api-key": "{{api_key}}" },
  }
);

const payment = await response.json();
console.log(payment.status);

import requests

response = requests.get(
    "https://api.sandbox.pesaswap.io/payments/pay_mbabizu24mvu3mela5njyhpit4",
    params={"force_sync": "true"},
    headers={"api-key": "{{api_key}}"},
)

payment = response.json()
print(payment["status"])

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.sandbox.pesaswap.io/payments/pay_mbabizu24mvu3mela5njyhpit4?force_sync=true",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "api-key: {{api_key}}",
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

Status reference

Status	What it means	What to do
`requires_customer_action`	The 3DS challenge is pending.	Redirect the customer to `next_action.redirect_to_url` if you haven’t already.
`processing`	The bank has the payment and is finalizing it.	Keep polling.
`succeeded`	The payment is settled.	Stop — settled.
`failed`	The bank declined the payment or the 3DS challenge failed.	Stop — failed.

Common errors

Missing return_url on a 3DS payment

When authentication_type is three_ds, return_url is required — without it the bank has nowhere to send the customer back to after the challenge.

Expired card

The connector declines the payment and the final status is failed.

Treating the return_url redirect as success

The redirect only means the customer’s browser came back to your site. Always confirm with GET /payments/{payment_id}?force_sync=true before marking the order paid.

Next steps

Quickstart

The full create-and-poll payment loop.

Wallet payments

M-Pesa, Airtel, and MTN MoMo.

Mandates and recurring

Save a card for repeat charges.

Refunds

Refund a settled card payment.

About Pesaswap

Payments Guide

Account Setup

Use Cases

Explore Pesaswap

Checklist for Production

FAQ

Card payments and 3DS

Status reference

Common errors

Next steps

Quickstart

Wallet payments

Mandates and recurring

Refunds

​Status reference

​Common errors

​Next steps

Quickstart

Wallet payments

Mandates and recurring

Refunds

Status reference

Common errors

Next steps