Initiate Order with Orchestrator.

Create an order with orchestator helper.

POST /orchestration/direct-orders

Initiate Order with Orchestrator.

cURL

curl --request POST \
  --url https://developersandbox-api.flutterwave.com/orchestration/direct-orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 12.34,
  "currency": "NGN",
  "reference": "<string>",
  "customer": {
    "email": "[e-mail]",
    "meta": {},
    "name": {
      "first": "King",
      "middle": "Leo",
      "last": "LeBron"
    },
    "phone": {
      "country_code": "234",
      "number": "08012345678"
    }
  },
  "payment_method": {
    "type": "card",
    "card": {
      "nonce": "<string>",
      "encrypted_expiry_month": "sQpvQEb7GrUCjPuEN/NmHiPl",
      "encrypted_expiry_year": "sgHNEDkJ/RmwuWWq/RymToU5",
      "encrypted_card_number": "sAE3hEDaDQ+yLzo4Py+Lx15OZjBGduHu/DcdILh3En0=",
      "encrypted_cvv": "tAUzH7Qjma7diGdi7938F/ESNA==",
      "card_holder_name": "Alex James"
    },
    "customer_id": "cus_3XarBILKQS",
    "meta": {}
  },
  "meta": {},
  "redirect_url": "<string>"
}
'

import requests

url = "https://developersandbox-api.flutterwave.com/orchestration/direct-orders"

payload = {
    "amount": 12.34,
    "currency": "NGN",
    "reference": "<string>",
    "customer": {
        "email": "[e-mail]",
        "meta": {},
        "name": {
            "first": "King",
            "middle": "Leo",
            "last": "LeBron"
        },
        "phone": {
            "country_code": "234",
            "number": "08012345678"
        }
    },
    "payment_method": {
        "type": "card",
        "card": {
            "nonce": "<string>",
            "encrypted_expiry_month": "sQpvQEb7GrUCjPuEN/NmHiPl",
            "encrypted_expiry_year": "sgHNEDkJ/RmwuWWq/RymToU5",
            "encrypted_card_number": "sAE3hEDaDQ+yLzo4Py+Lx15OZjBGduHu/DcdILh3En0=",
            "encrypted_cvv": "tAUzH7Qjma7diGdi7938F/ESNA==",
            "card_holder_name": "Alex James"
        },
        "customer_id": "cus_3XarBILKQS",
        "meta": {}
    },
    "meta": {},
    "redirect_url": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 12.34,
    currency: 'NGN',
    reference: '<string>',
    customer: {
      email: '[e-mail]',
      meta: {},
      name: {first: 'King', middle: 'Leo', last: 'LeBron'},
      phone: {country_code: '234', number: '08012345678'}
    },
    payment_method: {
      type: 'card',
      card: {
        nonce: '<string>',
        encrypted_expiry_month: 'sQpvQEb7GrUCjPuEN/NmHiPl',
        encrypted_expiry_year: 'sgHNEDkJ/RmwuWWq/RymToU5',
        encrypted_card_number: 'sAE3hEDaDQ+yLzo4Py+Lx15OZjBGduHu/DcdILh3En0=',
        encrypted_cvv: 'tAUzH7Qjma7diGdi7938F/ESNA==',
        card_holder_name: 'Alex James'
      },
      customer_id: 'cus_3XarBILKQS',
      meta: {}
    },
    meta: {},
    redirect_url: '<string>'
  })
};

fetch('https://developersandbox-api.flutterwave.com/orchestration/direct-orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://developersandbox-api.flutterwave.com/orchestration/direct-orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 12.34,
    'currency' => 'NGN',
    'reference' => '<string>',
    'customer' => [
        'email' => '[e-mail]',
        'meta' => [
                
        ],
        'name' => [
                'first' => 'King',
                'middle' => 'Leo',
                'last' => 'LeBron'
        ],
        'phone' => [
                'country_code' => '234',
                'number' => '08012345678'
        ]
    ],
    'payment_method' => [
        'type' => 'card',
        'card' => [
                'nonce' => '<string>',
                'encrypted_expiry_month' => 'sQpvQEb7GrUCjPuEN/NmHiPl',
                'encrypted_expiry_year' => 'sgHNEDkJ/RmwuWWq/RymToU5',
                'encrypted_card_number' => 'sAE3hEDaDQ+yLzo4Py+Lx15OZjBGduHu/DcdILh3En0=',
                'encrypted_cvv' => 'tAUzH7Qjma7diGdi7938F/ESNA==',
                'card_holder_name' => 'Alex James'
        ],
        'customer_id' => 'cus_3XarBILKQS',
        'meta' => [
                
        ]
    ],
    'meta' => [
        
    ],
    'redirect_url' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://developersandbox-api.flutterwave.com/orchestration/direct-orders"

	payload := strings.NewReader("{\n  \"amount\": 12.34,\n  \"currency\": \"NGN\",\n  \"reference\": \"<string>\",\n  \"customer\": {\n    \"email\": \"[e-mail]\",\n    \"meta\": {},\n    \"name\": {\n      \"first\": \"King\",\n      \"middle\": \"Leo\",\n      \"last\": \"LeBron\"\n    },\n    \"phone\": {\n      \"country_code\": \"234\",\n      \"number\": \"08012345678\"\n    }\n  },\n  \"payment_method\": {\n    \"type\": \"card\",\n    \"card\": {\n      \"nonce\": \"<string>\",\n      \"encrypted_expiry_month\": \"sQpvQEb7GrUCjPuEN/NmHiPl\",\n      \"encrypted_expiry_year\": \"sgHNEDkJ/RmwuWWq/RymToU5\",\n      \"encrypted_card_number\": \"sAE3hEDaDQ+yLzo4Py+Lx15OZjBGduHu/DcdILh3En0=\",\n      \"encrypted_cvv\": \"tAUzH7Qjma7diGdi7938F/ESNA==\",\n      \"card_holder_name\": \"Alex James\"\n    },\n    \"customer_id\": \"cus_3XarBILKQS\",\n    \"meta\": {}\n  },\n  \"meta\": {},\n  \"redirect_url\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://developersandbox-api.flutterwave.com/orchestration/direct-orders")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 12.34,\n  \"currency\": \"NGN\",\n  \"reference\": \"<string>\",\n  \"customer\": {\n    \"email\": \"[e-mail]\",\n    \"meta\": {},\n    \"name\": {\n      \"first\": \"King\",\n      \"middle\": \"Leo\",\n      \"last\": \"LeBron\"\n    },\n    \"phone\": {\n      \"country_code\": \"234\",\n      \"number\": \"08012345678\"\n    }\n  },\n  \"payment_method\": {\n    \"type\": \"card\",\n    \"card\": {\n      \"nonce\": \"<string>\",\n      \"encrypted_expiry_month\": \"sQpvQEb7GrUCjPuEN/NmHiPl\",\n      \"encrypted_expiry_year\": \"sgHNEDkJ/RmwuWWq/RymToU5\",\n      \"encrypted_card_number\": \"sAE3hEDaDQ+yLzo4Py+Lx15OZjBGduHu/DcdILh3En0=\",\n      \"encrypted_cvv\": \"tAUzH7Qjma7diGdi7938F/ESNA==\",\n      \"card_holder_name\": \"Alex James\"\n    },\n    \"customer_id\": \"cus_3XarBILKQS\",\n    \"meta\": {}\n  },\n  \"meta\": {},\n  \"redirect_url\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://developersandbox-api.flutterwave.com/orchestration/direct-orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 12.34,\n  \"currency\": \"NGN\",\n  \"reference\": \"<string>\",\n  \"customer\": {\n    \"email\": \"[e-mail]\",\n    \"meta\": {},\n    \"name\": {\n      \"first\": \"King\",\n      \"middle\": \"Leo\",\n      \"last\": \"LeBron\"\n    },\n    \"phone\": {\n      \"country_code\": \"234\",\n      \"number\": \"08012345678\"\n    }\n  },\n  \"payment_method\": {\n    \"type\": \"card\",\n    \"card\": {\n      \"nonce\": \"<string>\",\n      \"encrypted_expiry_month\": \"sQpvQEb7GrUCjPuEN/NmHiPl\",\n      \"encrypted_expiry_year\": \"sgHNEDkJ/RmwuWWq/RymToU5\",\n      \"encrypted_card_number\": \"sAE3hEDaDQ+yLzo4Py+Lx15OZjBGduHu/DcdILh3En0=\",\n      \"encrypted_cvv\": \"tAUzH7Qjma7diGdi7938F/ESNA==\",\n      \"card_holder_name\": \"Alex James\"\n    },\n    \"customer_id\": \"cus_3XarBILKQS\",\n    \"meta\": {}\n  },\n  \"meta\": {},\n  \"redirect_url\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

201

{
  "message": "<string>",
  "data": {
    "id": "ord_WRq7L4TM8p",
    "amount": 12.34,
    "fees": [
      {
        "type": "vat",
        "amount": 12.3
      }
    ],
    "billing_details": {
      "email": "[e-mail]",
      "name": {
        "first": "King",
        "middle": "Leo",
        "last": "LeBron"
      },
      "phone": {
        "country_code": "234",
        "number": "08012345678"
      }
    },
    "currency": "NGN",
    "customer_id": "cus_3XarBILKQS",
    "description": "Payment for a Suit Skirt",
    "meta": {},
    "next_action": {
      "type": "redirect_url",
      "redirect_url": {
        "url": "https://developer-sandbox-ui-sit.flutterwave.cloud/redirects?opay&token=eyJhbGciOiJIUzI1NiJ9.eyJjbGllbnRJZCI6ImNiYThhMTkwLTE2OGUtNGNmZS05NmY5LTE2NDZhYjFhOWNkYiIsImNoYXJnZUlkIjoiY2hnX25PTmdlQUdZOTciLCJzdWIiOiJjYmE4YTE5MC0xNjhlLTRjZmUtOTZmOS0xNjQ2YWIxYTljZGIiLCJpYXQiOjE3MzgzMTc3MTAsImV4cCI6MTczODMxODAxMH0.QgLoZYfNhHJOJJvOsLA9eLoxOjGF0qnuehPMgMP4zD4"
      }
    },
    "payment_method_details": {
      "id": "pmd_WRq7L4TM8p",
      "type": "card",
      "card": {
        "expiry_month": "09",
        "expiry_year": "32",
        "first6": "123412",
        "last4": "1234",
        "network": "MASTERCARD",
        "billing_address": {
          "city": "New York",
          "country": "US",
          "line1": "123 Main Street",
          "postal_code": "10001",
          "state": "New York",
          "line2": "Apt 4B"
        },
        "cof": {
          "enabled": true,
          "agreement_id": "Agreement00w02W1",
          "recurring_amount_variability": "VARIABLE",
          "agreement_type": "UNSCHEDULED",
          "trace_id": "123456789"
        },
        "card_holder_name": "Alex James"
      },
      "customer_id": "cus_3XarBILKQS",
      "meta": {},
      "device_fingerprint": "62wd23423rq324323qew1",
      "client_ip": "154.123.220.1",
      "created_datetime": "2024-12-03T13:54:21.546559974Z"
    },
    "redirect_url": "https://flutterwave.com",
    "reference": "<string>",
    "created_datetime": "2025-03-27T10:00:00Z"
  }
}

{
  "status": "failed",
  "error": {
    "type": "REQUEST_NOT_VALID",
    "code": "10400",
    "message": "Request is not valid",
    "validation_errors": [
      {
        "field_name": "amount",
        "message": "must not be null"
      }
    ]
  }
}

{
  "status": "failed",
  "message": "UNAUTHORIZED",
  "error": {
    "type": "UNAUTHORIZED",
    "code": "10401",
    "message": "unauthorized"
  }
}

{
  "status": "failed",
  "message": "<string>",
  "error": {
    "type": "FORBIDDEN",
    "code": "10403",
    "message": "Forbidden"
  }
}

{
  "status": "failed",
  "message": "<string>",
  "error": {
    "type": "RESOURCE_CONFLICT",
    "code": "10409",
    "message": "Resource conflict"
  }
}

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> · required

The payment amount in decimals.

Required range: x >= 0.01

Example:

12.34

currency · enum<string> · required

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"

reference · string · required

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\-]+$

customer · object · required

Show child attributes

payment_method · object · required

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Option 8

Show child attributes

meta · object

Show child attributes

redirect_url · string

Specifies the URL to redirect to.

authorization · object

3DS authorization object.

Show child attributes

Response

201

application/json

OK

status · enum<string>

Available options: success, failed

message · string

data · object

Show child attributes