Payment Orchestrator flow

Unlike the main payment flow, which requires creating customer and payment_method entities first, the payment orchestrator allows you to set up both entities simultaneously. To properly use this helper endpoint, Here is a visual representation of what happens when you call the endpoint.

[Add flow diagram here].

While we don't recommend this method for every integration, it is great for situations where you want to charge the customer quickly and would not be repeating the charge. This flow supports all our payment methods (see the full list of supported payment methods here).

Initiating a Charge

When charging a customer using this method, collect their PII, payment data, and other transaction details like amount, currency, reference, etc. Send your request to the direct charge endpoint.

Sample Request - Card

# HTTP Verb: POST
# Endpoint:https://api-sit.flutterwave.cloud/developersandbox/orchestration/direct-charges

# Header: 
{
	"X-Trace-Id": <{{$randomUUID}}>
	"X-Idempotency-Key": <{{$randomUUID}}>
	"X-Scenario-Key": <scenario:auth_pin&issuer:approved>
}

# Body:
{
    "amount": "200",
    "currency": "USD",
    "reference": "YOUR_EXAMPLE_REFERENCE",
    "payment_method": {
        "type": "card",
        "card": {
            "nonce": "n0Ad6mOzVnLI",
            "encrypted_expiry_month": "sQpvQEb7GrUCjPuEN/NmHiPl",
            "encrypted_expiry_year": "sgHNEDkJ/RmwuWWq/RymToU5",
            "encrypted_card_number": "sAE3hEDaDQ+yLzo4Py+Lx15OZjBGduHu/DcdILh3En0=",
            "encrypted_cvv": "tAUzH7Qjma7diGdi7938F/ESNA=="
        }
    },
    "redirect_url": "http://www.flutterwave.com",
    "customer": {
        "address": {
            "country": "US",
            "city": "San Francisco",
            "state": "California",
            "postal_code": "10001",
            "line1": "123 Main Street",
        },
        "phone": {
            "country_code": "41",
            "number": "7069423351"
        },
        "name": {
            "middle": "Cornelius",
            "last": "Oluwole",
            "first": "Hassan"
        },
        "email": "[email protected]"
    }
}

Depending on the payment method you choose to charge your customer with, your request would vary slightly. Here are more examples to aid your integration.

[Add example requests]

You can send additional information in your request. check the API reference for the full list of supported parameters on the orchestrator endpoint.

📘

We still enforce the required fields used to create the customer and payment method entities in this request. Read the API reference for customers and payment methods to see the full list of mandatory fields.

Completing Payments

After initiating the charge with the payment orchestrator, We return the next steps in the response as data.next_action. This object informs you about the expected action required to complete the payment.

There are three categories of next action results:

1. Authorization
2. Redirects
3. XYZ

Authorisation actions are customer inputs for authorizing card transactions with their banks. Actions like entering pins, soft tokens (OTPs) and billing addresses all fall under this category of next actions.
[Add example]

Redirects contain instructions for the merchant to redirect their customers to. These are typically used to complete 3DS card payments and mobile money transactions. In this scenario, the customer's transactions remain pending under redirection is completed.

Redirect - 200 OK

{
    "status": "success",
    "message": "Charge created",
    "data": {
        "id": "chg_RCDsCBDyaV",
        ...
        "next_action": {
            "type": "redirect_url",
            "redirect_url": {
                "url": "https://developer-sandbox-ui-sit.flutterwave.cloud/redirects?card&token=eyJhbGciOiJIUzI1NiJ9.eyJjbGllbnRJZCI6ImFjODMxOTNlLWFhMmItNDc2ZS1hZTNjLTMxYmVmMTc4NDUxZCIsImNoYXJnZUlkIjoiY2hnX1JDRHNDQkR5YVYiLCJzdWIiOiJhYzgzMTkzZS1hYTJiLTQ3NmUtYWUzYy0zMWJlZjE3ODQ1MWQiLCJpYXQiOjE3MzA5NjQ1MTIsImV4cCI6MTczMDk2NDgxMn0.tMv1VZ4WevvZ_dg37AzYnhj0Z1YtXK_tQIOJcErNscI"
            }
        },
        "payment_method_details": {},
        "status": "pending",
        ...
    }
}