Creating Charges

Process charges from your backend using FayaPay's API.


Once you’ve securely collected your customer’s payment details using Checkout, you can charge the source immediately or save it for later.

Unlike collection, which occurs in the browser, charge attempts are made from your server, normally using one of our client libraries.

On your server, grab the source id in the POST parameters submitted by your form via fp_source_id. From there, it’s one simple API call to charge the source:

curl -X POST 'https://api.fayapay.io/v1/charges' \
    -H 'Authorization: {{ api-key }}' \
    -H "X-Idempotency-Key: {{ your-unique-reference }}" \
    -H 'Content-Type: application/json' \
    -d '{ 
            "reference": "{{ your-unique-reference }}", 
            "source": "{{ source-id }}", 
            "amount": 100, 
            "currency": "GHS",
            "description": "Optional description",
        }'

As a convenience, if you’re logged in while reading this page, we’ve pre-filled the example with your test API key. Only you can see this value. This will authenticate you to FayaPay, so keep it secret and keep it safe.

Remember to replace the test key with your live key in production. You can manage your keys from the Dashboard.

That’s it! If the charge creation request succeeds, we will process the charge and notify you via webhooks of the status. If the charge creation attempt fails, we’ll return an error instead.

Note that a source can only be used once, and within a few minutes of creation. To support multiple charges, future charges, or subscriptions, attach the source to a customer instead of charging it.

You can only attach Reuseable sources to customers. Learn more about sources and customers.

Asynchronicity

Creating charges using FayaPay is always an asynchronous process.

The charge object returned to your code has a state field which will initially be Pending. As the charge state changes, we will send you webhook calls with either the charge.succeeded or charge.failed event types corresponding to the Succeeded and Failed states.

Once you receive these events, update your order state accordingly and notify your customer.


Dynamic statement descriptor

By default, with supported payment channels, your account’s statement descriptor appears on customer statements whenever you charge a source. Additionally, you can set the statement descriptor dynamically on every charge request with the statementDescriptor parameter:

curl -X POST 'https://api.fayapay.io/v1/charges' \
    -H 'Authorization: {{ api-key }}' \
    -H "X-Idempotency-Key: {{ your-unique-reference }}" \
    -H 'Content-Type: application/json' \
    -d '{ 
            "reference": "{{ your-unique-reference }}", 
            "source": "{{ source-id }}", 
            "amount": 100, 
            "currency": "GHS",
            "statementDescriptor":"Optional dynamic descriptor",
        }'

Statement descriptors are limited to 22 characters, cannot use the special characters <, >, ', ", or *, and must not be a valid number.

When setting the statement descriptor, the dynamic portion is appended to the settlement merchant’s statement descriptor (separated by *). For example, if your account statement descriptor is set to Mokudi, and you set a dynamic descriptor of Cash, the full descriptor will be Mokudi* Cash.

The * and empty space count towards the 22 character limit, with the account and dynamic descriptor each allocated 10 characters. This means that if either descriptor is longer than 10 characters, it will be truncated. However, if one of the descriptors is shorter than the allocated count, the extra characters will be given to the other descriptor. e.g. ELEVENCHARS and NINECHARS will give you ELEVENCHARS* NINECHARS while MANYMORECHARS and NINECHARS will give you MANYMORECHA* NINECHARS.


Storing information in metadata

FayaPay supports adding metadata to the most common requests you make, such as processing charges. Metadata isn’t shown to customers or factored into whether or not a request is processed.

Through metadata, you can associate other information—meaningful to you—with FayaPay activity. Any metadata you include is viewable in the Dashboard (e.g. when looking at the a charge's detail page), and is also available in common reports and exports. As an example, your store’s order ID can be attached to the charge used to pay for that order. Doing so allows you, your accountant, or your finance team to easily reconcile charges in FayaPay to orders in your system.

curl -X POST 'https://api.fayapay.io/v1/charges' \
    -H 'Authorization: {{ api-key }}' \
    -H "X-Idempotency-Key: {{ your-unique-reference }}" \
    -H 'Content-Type: application/json' \
    -d '{ 
            "reference": "{{ your-unique-reference }}", 
            "source": "{{ source-id }}", 
            "amount": 100, 
            "currency": "GHS",
            "metadata": {
                "key1": "value1",
                "key2": "value2",
            },
        }'

Do not store any sensitive information (personally identifiable information, payment details, etc.) as metadata or in the charge’s description parameter.