Skip to main content
POST
/
checkout
/
sessions
Create a checkout session
curl --request POST \
  --url https://developersandbox-api.flutterwave.com/checkout/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 12.34,
  "currency": "NGN",
  "customer_id": "<string>",
  "redirect_url": "<string>",
  "reference": "<string>",
  "max_retry_attempts": 3,
  "session_duration": 1442
}
'
{
  "status": "success",
  "message": "<string>",
  "data": {
    "id": "<string>",
    "amount": 12.34,
    "currency": "NGN",
    "customer_id": "<string>",
    "checkout_url": "<string>",
    "redirect_url": "<string>",
    "reference": "<string>",
    "created_datetime": "2023-11-07T05:31:56Z",
    "max_retry_attempts": 3,
    "session_duration": 1442
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
X-Trace-Id
string

A unique identifier to track this operation. It must be between 12 and 255 characters in length.

Required string length: 12 - 255
​
X-Idempotency-Key
string

A unique identifier to prevent duplicate requests. It must be between 12 and 255 characters in length.

Required string length: 12 - 255
​
X-Scenario-Key
string

An optional scenario key that can be used to simulate specific behaviors or test different scenarios within the API. Providing this header allows you to trigger predefined responses or alter data based on the key's value, which can be useful for testing, development, or demonstrating specific functionalities. The key should be a string of 1 to 1000 characters.

Body

application/json
​
amount
number<decimal>

The payment amount in decimals.

Required range: x >= 0.01
Example:

12.34

​
currency
enum<string>

ISO 4217 currency code.

Available options:
AED,
AFN,
ALL,
AMD,
ANG,
AOA,
AQD,
ARS,
AUD,
AZN,
BAM,
BBD,
BDT,
BGN,
BHD,
BIF,
BMD,
BND,
BOB,
BRL,
BSD,
BWP,
BYR,
BZD,
CAD,
CDF,
CHF,
CLP,
CNY,
COP,
CRC,
CUP,
CVE,
CYP,
CZK,
DJF,
DKK,
DOP,
DZD,
ECS,
EEK,
EGP,
ETB,
EUR,
FJD,
FKP,
GBP,
GEL,
GGP,
GHS,
GIP,
GMD,
GNF,
GTQ,
GYD,
HKD,
HNL,
HRK,
HTG,
HUF,
IDR,
ILS,
INR,
IQD,
IRR,
ISK,
JMD,
JOD,
JPY,
KES,
KGS,
KHR,
KMF,
KPW,
KRW,
KWD,
KYD,
KZT,
LAK,
LBP,
LKR,
LRD,
LSL,
LTL,
LVL,
LYD,
MAD,
MDL,
MGA,
MKD,
MMK,
MNT,
MOP,
MRO,
MTL,
MUR,
MVR,
MWK,
MXN,
MYR,
MZN,
NAD,
NGN,
NIO,
NOK,
NPR,
NZD,
OMR,
PAB,
PEN,
PGK,
PHP,
PKR,
PLN,
PYG,
QAR,
RON,
RSD,
RUB,
RWF,
SAR,
SBD,
SCR,
SDG,
SEK,
SGD,
SKK,
SLL,
SOS,
SRD,
STD,
SVC,
SYP,
SZL,
THB,
TJS,
TMT,
TND,
TOP,
TRY,
TTD,
TWD,
TZS,
UAH,
UGX,
USD,
UYU,
UZS,
VEF,
VND,
VUV,
XAF,
XCD,
XOF,
XPF,
YER,
ZAR,
ZMK,
ZWD,
ZMW
Example:

"NGN"

​
customer_id
string

ID of the customer

​
redirect_url
string

Specifies the URL to redirect to after payment.

​
reference
string

A custom identifier to track the transaction, This must be unique across all your transactions.

Required string length: 6 - 42
Pattern: ^[a-zA-Z0-9\-]+$
​
max_retry_attempts
integer
default:3

The maximum number of retry attempts to complete checkout

Required range: 0 <= x <= 10
​
session_duration
integer

The session duration (in minutes) to keep active. You can always generate a new checkout session if expired

Required range: 5 <= x <= 2880

Response

OK

​
status
enum<string>
Available options:
success,
failed
​
message
string
​
data
object