NAV Navbar
Shell

Introduction

The FayaPay API is RESTful. It uses built-in HTTP features, like HTTP verbs and HTTP status codes, which are understood by off-the-shelf HTTP clients.

We do not support cross-origin resource sharing, preventing you from interacting with our API from a client-side web application as this might open you up to vulnerability.

You have both test mode and live mode API keys. Simply use the appropriate key to perform a live or test transaction.

The only difference between live and test keys is that requests made with test keys never hit the payment networks. Everything else is the same as in live.

Authentication

To authenticate your requests, pass your secret key in via the Authorization header:


curl --request GET \
  --header 'authorization: {{ API KEY }}' 

Make sure to replace with your API key.

API keys are managed in your Dashboard.

To use your API key, you pass it in the HTTP Authorization header.

All API requests must be authenticated and made over HTTPS else they will fail.

Errors

FayaPay uses conventional HTTP response codes to indicate the status of an API request.

Non 5xx errors can generally be handled programmatically. These return an ErrorResponse in the body.

HTTP Status code summary

Status Code Meaning
400 - Bad Request The request was unacceptable, often due to failed validation.
401 - Unauthorized Request was not properly authenticated.
403 - Forbidden You are not authorized to access this resource due to missing permissions.
404 - Not Found The requested resource does not exist.
406 - Not Acceptable You requested an unsupported format. Set Accept header to application/json.
409 - Conflict You tried to reuse a reference.
429 - Too Many Requests You're exceeding your rate limits. Implement exponential backoff in your requests.
5xx - Server Errors Something went wrong on our end (these are rare).

Resources

Charges

List Charges

Code samples

curl --request GET \
  --url https://api.fayapay.io/v1/Charges \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}'

GET /v1/Charges

Parameters

Name In Type Required Description
EndingBefore query string false A cursor for use in pagination.
StartingAfter query string false A cursor for use in pagination.
Limit query integer(int32) false A limit on the number of objects to be returned, between 1 and 50. Defaults to 10.

Detailed descriptions

EndingBefore: A cursor for use in pagination. EndingBefore is an object ID that defines your place in the list. Specifying EndingBefore will load all objects that were created before the object you specified. For instance, if you make a list request and receive 50 objects, starting with obj_foo, your subsequent call can include EndingBefore=obj_foo in order to fetch the previous page of the list.

StartingAfter: A cursor for use in pagination. StartingAfter is an object ID that defines your place in the list. Specifying StartingAfter will load all objects that were created after the object you specified. For instance, if you make a list request and receive 50 objects, ending with obj_foo, your subsequent call can include StartingAfter=obj_foo in order to fetch the next page of the list.

Example responses

200 Response

{
  "object": "string",
  "data": [
    {
      "object": "string",
      "id": "string",
      "reference": "string",
      "sourceId": "string",
      "customerId": "string",
      "amount": 0,
      "amountRefunded": 0,
      "fee": 0,
      "currency": "string",
      "statementDescriptor": "string",
      "description": "string",
      "paid": true,
      "metadata": {
        "property1": "string",
        "property2": "string"
      },
      "receiptId": "string",
      "receiptEmail": "string",
      "receiptPhone": "string",
      "failureCode": "None",
      "failureMessage": "string",
      "state": "Pending",
      "livemode": true,
      "createdAt": "2019-06-17T16:06:13Z"
    }
  ],
  "nextCursor": "string",
  "previousCursor": "string"
}

Responses

Status Meaning Description Schema
200 OK The list of Charge objects ListResponseOfChargeDTO
400 Bad Request Bad Request ErrorResponse

Create a Charge

Code samples

curl --request POST \
  --url https://api.fayapay.io/v1/Charges \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}' \
  --header 'content-type: application/json-patch+json' \
  --data '{"reference":"string","source":"string","customer":"string","amount":0,"currency":"str","statementDescriptor":"string","description":"string","metadata":{"property1":"string","property2":"string"}}'

POST /v1/Charges

You can either charge a Customer or a Source. If Customer is specified in addition to Source, then the Source must either be attached to the customer or unattached.

Body parameter

{
  "reference": "string",
  "source": "string",
  "customer": "string",
  "amount": 0,
  "currency": "str",
  "statementDescriptor": "string",
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Parameters

Name In Type Required Description
body body CreateChargeRequest true The create request
reference body string true Your unique reference.
source body string false The ID of the source to charge.
customer body string false The ID of the customer to charge.
amount body integer(int32) true A positive integer in the smallest currency unit (e.g. 100 pesewas to charge 1.00GHS) representing how much to charge.
currency body string true Three-letter ISO currency code, in uppercase. Must be a supported currency.
statementDescriptor body string false Extra information about the charge.
description body string false An arbitrary string attached to the charge.
metadata body object false Hash of key-value pairs that you can attach to an object.
» additionalProperties body string false none

Detailed descriptions

reference: Your unique reference. If a charge already exists with this reference, the request will fail with 409 status code and ErrorCode will be set to duplicate_reference. For better resiliency, set the X-IDEMPOTENCY-KEY header to this as well.

source: The ID of the source to charge. If the source is not attached to a customer, it is consumed.

customer: The ID of the customer to charge. If Source is not specified, the default customer source is charged. If an unattached source is specified, this will only associate the customer with the charge however, the source is still consumed.

amount: A positive integer in the smallest currency unit (e.g. 100 pesewas to charge 1.00GHS) representing how much to charge. The minimum amount is 100 (1.00GHS).

currency: Three-letter ISO currency code, in uppercase. Must be a supported currency. Supported currencies: GHS.

statementDescriptor: Extra information about the charge. This will appear on the customer’s statement. Maximum length: 22 characters.

description: An arbitrary string attached to the charge. Displayed in the dashboard and to customers e.g. in receipts and invoices.

metadata: Hash of key-value pairs that you can attach to an object. This is useful for storing additional information about the object in a structured format. Ideal for storing correlating information such as your internal Order Number or for tracking actions, such as detailing refunds and reasons. e.g. {"order_id": "order12345", "refunded": "Full amount", "refund_reason": "out of stock"}

Example responses

200 Response

{
  "object": "string",
  "id": "string",
  "reference": "string",
  "sourceId": "string",
  "customerId": "string",
  "amount": 0,
  "amountRefunded": 0,
  "fee": 0,
  "currency": "string",
  "statementDescriptor": "string",
  "description": "string",
  "paid": true,
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "receiptId": "string",
  "receiptEmail": "string",
  "receiptPhone": "string",
  "failureCode": "None",
  "failureMessage": "string",
  "state": "Pending",
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Responses

Status Meaning Description Schema
200 OK The Charge object ChargeDTO
400 Bad Request Bad Request ErrorResponse
409 Conflict Conflict ErrorResponse

Fetch a Charge

Code samples

curl --request GET \
  --url https://api.fayapay.io/v1/Charges/string \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}'

GET /v1/Charges/{ChargeId}

Parameters

Name In Type Required Description
ChargeId path string true The id of the charge

Example responses

200 Response

{
  "object": "string",
  "id": "string",
  "reference": "string",
  "sourceId": "string",
  "customerId": "string",
  "amount": 0,
  "amountRefunded": 0,
  "fee": 0,
  "currency": "string",
  "statementDescriptor": "string",
  "description": "string",
  "paid": true,
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "receiptId": "string",
  "receiptEmail": "string",
  "receiptPhone": "string",
  "failureCode": "None",
  "failureMessage": "string",
  "state": "Pending",
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Responses

Status Meaning Description Schema
200 OK The Charge object ChargeDTO

Update a Charge

Code samples

curl --request POST \
  --url https://api.fayapay.io/v1/Charges/ \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}' \
  --header 'content-type: application/json-patch+json' \
  --data '{"customer":"string","description":"string","metadata":{"property1":"string","property2":"string"}}'

POST /v1/Charges/{ChargeId}

Updating is a patch operation. Only set the keys of the properties you wish to update. Properties with null values are ignored.

Body parameter

{
  "customer": "string",
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Parameters

Name In Type Required Description
chargeId path string true The id of the charge
body body UpdateChargeRequest true The update request
customer body string false The ID of an existing customer that will be associated with this request.
description body string false An arbitrary string attached to the charge.
metadata body object false Hash of key-value pairs that you can attach to an object.
» additionalProperties body string false none

Detailed descriptions

customer: The ID of an existing customer that will be associated with this request. This field may only be updated if there is no existing associated customer with this charge. If already associated, the request will fail.

description: An arbitrary string attached to the charge. Displayed in the dashboard and to customers e.g. in receipts and invoices.

metadata: Hash of key-value pairs that you can attach to an object. This is useful for storing additional information about the object in a structured format. Ideal for storing correlating information such as your internal Order Number or for tracking actions, such as detailing refunds and reasons. e.g. {"order_id": "order12345", "refunded": "Full amount", "refund_reason": "out of stock"} Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty hash.

Example responses

200 Response

{
  "object": "string",
  "id": "string",
  "reference": "string",
  "sourceId": "string",
  "customerId": "string",
  "amount": 0,
  "amountRefunded": 0,
  "fee": 0,
  "currency": "string",
  "statementDescriptor": "string",
  "description": "string",
  "paid": true,
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "receiptId": "string",
  "receiptEmail": "string",
  "receiptPhone": "string",
  "failureCode": "None",
  "failureMessage": "string",
  "state": "Pending",
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Responses

Status Meaning Description Schema
200 OK The Charge object ChargeDTO
400 Bad Request Bad Request ErrorResponse

Refund a charge

Code samples

curl --request POST \
  --url https://api.fayapay.io/v1/Charges//Refunds \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}' \
  --header 'content-type: application/json-patch+json' \
  --data '{"reference":"string","amount":0,"description":"string","metadata":{"property1":"string","property2":"string"}}'

POST /v1/Charges/{ChargeId}/Refunds

You can either refund a Charge fully or partially. To make a partial refund, pass in an Amount. Omit it to issue a full refund. The charge must have been created directly by you. Charges created via other methods e.g. Billing or Orders cannot be refunded using this method.

Body parameter

{
  "reference": "string",
  "amount": 0,
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Parameters

Name In Type Required Description
chargeId path string true The id of the charge
body body RefundChargeRequest true The refund request
reference body string true Your unique reference.
amount body integer(int32) false A positive integer in the smallest currency unit (e.g. 100 pesewas to charge 1.00GHS) representing how much to refund.
description body string false An arbitrary string attached to the refund.
metadata body object false Hash of key-value pairs that you can attach to an object.
» additionalProperties body string false none

Detailed descriptions

reference: Your unique reference. If a refund already exists with this reference, the request will fail with 409 status code and ErrorCode will be set to duplicate_reference. For better resiliency, set the X-IDEMPOTENCY-KEY header to this as well.

amount: A positive integer in the smallest currency unit (e.g. 100 pesewas to charge 1.00GHS) representing how much to refund. The minimum amount is 100 (1.00GHS). Omit to issue a full refund. Must not exceed the original charge amount.

description: An arbitrary string attached to the refund. Displayed in the dashboard and to customers e.g. in receipts and invoices.

metadata: Hash of key-value pairs that you can attach to an object. This is useful for storing additional information about the object in a structured format. Ideal for storing correlating information such as your internal Order Number or for tracking actions, such as detailing refunds and reasons. e.g. {"order_id": "order12345", "refunded": "Full amount", "refund_reason": "out of stock"}

Example responses

200 Response

{
  "object": "string",
  "id": "string",
  "reference": "string",
  "chargeId": "string",
  "amount": 0,
  "currency": "string",
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "failureCode": "None",
  "failureMessage": "string",
  "state": "Pending",
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Responses

Status Meaning Description Schema
200 OK The Refund object RefundDTO
400 Bad Request Bad Request ErrorResponse
409 Conflict Conflict ErrorResponse

Customers

List Customers

Code samples

curl --request GET \
  --url https://api.fayapay.io/v1/Customers \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}'

GET /v1/Customers

Parameters

Name In Type Required Description
EndingBefore query string false A cursor for use in pagination.
StartingAfter query string false A cursor for use in pagination.
Limit query integer(int32) false A limit on the number of objects to be returned, between 1 and 50. Defaults to 10.

Detailed descriptions

EndingBefore: A cursor for use in pagination. EndingBefore is an object ID that defines your place in the list. Specifying EndingBefore will load all objects that were created before the object you specified. For instance, if you make a list request and receive 50 objects, starting with obj_foo, your subsequent call can include EndingBefore=obj_foo in order to fetch the previous page of the list.

StartingAfter: A cursor for use in pagination. StartingAfter is an object ID that defines your place in the list. Specifying StartingAfter will load all objects that were created after the object you specified. For instance, if you make a list request and receive 50 objects, ending with obj_foo, your subsequent call can include StartingAfter=obj_foo in order to fetch the next page of the list.

Example responses

200 Response

{
  "object": "string",
  "data": [
    {
      "object": "string",
      "id": "string",
      "name": "string",
      "email": "string",
      "phone": "string",
      "description": "string",
      "metadata": {
        "property1": "string",
        "property2": "string"
      },
      "livemode": true,
      "createdAt": "2019-06-17T16:06:13Z"
    }
  ],
  "nextCursor": "string",
  "previousCursor": "string"
}

Responses

Status Meaning Description Schema
200 OK The list of Customer objects ListResponseOfCustomerDTO

Create a Customer

Code samples

curl --request POST \
  --url https://api.fayapay.io/v1/Customers \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}' \
  --header 'content-type: application/json-patch+json' \
  --data '{"name":"string","email":"user@example.com","phone":"string","description":"string","metadata":{"property1":"string","property2":"string"}}'

POST /v1/Customers

Body parameter

{
  "name": "string",
  "email": "user@example.com",
  "phone": "string",
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Parameters

Name In Type Required Description
body body CreateCustomerRequest true The create request
name body string true The Name of the customer.
email body string(email) false An optional email for the customer.
phone body string false An optional phone number for the customer.
description body string false An arbitrary string attached to the customer.
metadata body object false Hash of key-value pairs that you can attach to an object.
» additionalProperties body string false none

Detailed descriptions

email: An optional email for the customer. Used by FayaPay to send receipts and notifications.

phone: An optional phone number for the customer. Used by FayaPay to send receipts and notifications. If set, phone must be a valid phone number, including the country code e.g. +233200123456

description: An arbitrary string attached to the customer. Displayed in the dashboard.

metadata: Hash of key-value pairs that you can attach to an object. This is useful for storing additional information about the object in a structured format. Ideal for storing additional information such as the customer's address. e.g. {"city": "Accra", "country": "customer_country", "address_line": "address"}

Example responses

200 Response

{
  "object": "string",
  "id": "string",
  "name": "string",
  "email": "string",
  "phone": "string",
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Responses

Status Meaning Description Schema
200 OK The Customer object CustomerDTO
400 Bad Request Bad Request ErrorResponse

Fetch a Customer

Code samples

curl --request GET \
  --url https://api.fayapay.io/v1/Customers/string \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}'

GET /v1/Customers/{Id}

Parameters

Name In Type Required Description
Id path string true The id of the customer

Example responses

200 Response

{
  "object": "string",
  "id": "string",
  "name": "string",
  "email": "string",
  "phone": "string",
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Responses

Status Meaning Description Schema
200 OK The Customer object CustomerDTO

Update a Customer

Code samples

curl --request POST \
  --url https://api.fayapay.io/v1/Customers/ \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}' \
  --header 'content-type: application/json-patch+json' \
  --data '{"name":"string","email":"user@example.com","phone":"string","description":"string","defaultSource":"string","metadata":{"property1":"string","property2":"string"}}'

POST /v1/Customers/{CustomerId}

Updating is a patch operation. Only set the keys of the properties you wish to update. Properties with null values are ignored.

Body parameter

{
  "name": "string",
  "email": "user@example.com",
  "phone": "string",
  "description": "string",
  "defaultSource": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Parameters

Name In Type Required Description
customerId path string true The id of the customer
body body UpdateCustomerRequest true The update request
name body string false The Name of the customer.
email body string(email) false An optional email for the customer.
phone body string false An optional phone number for the customer.
description body string false An arbitrary string attached to the customer.
defaultSource body string false Id of the Source to set as customer's default.
metadata body object false Hash of key-value pairs that you can attach to an object.
» additionalProperties body string false none

Detailed descriptions

email: An optional email for the customer. Used by FayaPay to send receipts and notifications.

phone: An optional phone number for the customer. Used by FayaPay to send receipts and notifications. If set, phone must be a valid phone number, including the country code e.g. +233200123456

description: An arbitrary string attached to the customer. Displayed in the dashboard.

metadata: Hash of key-value pairs that you can attach to an object. This is useful for storing additional information about the object in a structured format. Ideal for storing additional information such as the customer's address. e.g. {"city": "Accra", "country": "customer_country", "address_line": "address"}

Example responses

200 Response

{
  "object": "string",
  "id": "string",
  "name": "string",
  "email": "string",
  "phone": "string",
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Responses

Status Meaning Description Schema
200 OK The Customer object CustomerDTO
400 Bad Request Bad Request ErrorResponse

Attach a source to a customer

Code samples

curl --request POST \
  --url https://api.fayapay.io/v1/Customers//Sources \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}' \
  --header 'content-type: application/json-patch+json' \
  --data '{"source":"string"}'

POST /v1/Customers/{CustomerId}/Sources

The source must be unattached, reuseable, chargeable (or pending) and not expired. Attaching a source does not affect the customer's default source.

Body parameter

{
  "source": "string"
}
<?xml version="1.0" encoding="UTF-8" ?>
<AttachSourceRequest>
  <source>string</source>
</AttachSourceRequest>

Parameters

Name In Type Required Description
customerId path string true The id of the customer
body body AttachSourceRequest true The attach request
source body string true Id of the Source to attach to the customer.

Example responses

200 Response

{
  "object": "string",
  "id": "string",
  "customerId": "string",
  "maskedName": "string",
  "currency": "string",
  "amount": 0,
  "statementDescriptor": "string",
  "type": "string",
  "useType": "Single",
  "flow": "None",
  "owner": {
    "name": "string",
    "email": "string",
    "phone": "string",
    "verifiedName": "string",
    "verifiedEmail": "string",
    "verifiedPhone": "string"
  },
  "returnUrl": "string",
  "clientSecret": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "redirectUrl": "string",
  "state": "Pending",
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Responses

Status Meaning Description Schema
200 OK The Customer object SourceDTO
400 Bad Request Bad Request ErrorResponse

Disbursements

List Disbursements

Code samples

curl --request GET \
  --url https://api.fayapay.io/v1/Disbursements \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}'

GET /v1/Disbursements

Parameters

Name In Type Required Description
EndingBefore query string false A cursor for use in pagination.
StartingAfter query string false A cursor for use in pagination.
Limit query integer(int32) false A limit on the number of objects to be returned, between 1 and 50. Defaults to 10.

Detailed descriptions

EndingBefore: A cursor for use in pagination. EndingBefore is an object ID that defines your place in the list. Specifying EndingBefore will load all objects that were created before the object you specified. For instance, if you make a list request and receive 50 objects, starting with obj_foo, your subsequent call can include EndingBefore=obj_foo in order to fetch the previous page of the list.

StartingAfter: A cursor for use in pagination. StartingAfter is an object ID that defines your place in the list. Specifying StartingAfter will load all objects that were created after the object you specified. For instance, if you make a list request and receive 50 objects, ending with obj_foo, your subsequent call can include StartingAfter=obj_foo in order to fetch the next page of the list.

Example responses

200 Response

{
  "object": "string",
  "data": [
    {
      "object": "string",
      "id": "string",
      "reference": "string",
      "amount": 0,
      "fee": 0,
      "currency": "string",
      "recipientName": "string",
      "recipientEmail": "string",
      "recipientAccountProvider": "string",
      "recipientAccountNumber": "string",
      "recipientAccountCountry": "string",
      "statementDescriptor": "string",
      "description": "string",
      "paid": true,
      "metadata": {
        "property1": "string",
        "property2": "string"
      },
      "receiptId": "string",
      "receiptEmail": "string",
      "receiptPhone": "string",
      "failureCode": "None",
      "failureMessage": "string",
      "state": "Pending",
      "livemode": true,
      "createdAt": "2019-06-17T16:06:13Z"
    }
  ],
  "nextCursor": "string",
  "previousCursor": "string"
}

Responses

Status Meaning Description Schema
200 OK The list of Disbursement objects ListResponseOfDisbursementDTO
400 Bad Request Bad Request ErrorResponse

Create a Disbursement

Code samples

curl --request POST \
  --url https://api.fayapay.io/v1/Disbursements \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}' \
  --header 'content-type: application/json-patch+json' \
  --data '{"reference":"string","amount":0,"currency":"str","recipientName":"string","recipientEmail":"user@example.com","recipientAccountProvider":"string","recipientAccountNumber":"string","recipientAccountCountry":"string","statementDescriptor":"string","description":"string","metadata":{"property1":"string","property2":"string"}}'

POST /v1/Disbursements

You can either disbursement a Customer or a Source. If Customer is specified in addition to Source, then the Source must either be attached to the customer or unattached.

Body parameter

{
  "reference": "string",
  "amount": 0,
  "currency": "str",
  "recipientName": "string",
  "recipientEmail": "user@example.com",
  "recipientAccountProvider": "string",
  "recipientAccountNumber": "string",
  "recipientAccountCountry": "string",
  "statementDescriptor": "string",
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Parameters

Name In Type Required Description
body body CreateDisbursementRequest true The create request
reference body string true Your unique reference.
amount body integer(int32) true A positive integer in the smallest currency unit (e.g. 100 pesewas to disbursement 1.00GHS) representing how much to disbursement.
currency body string true Three-letter ISO currency code, in uppercase. Must be a supported currency.
recipientName body string false The recipient's name.
recipientEmail body string(email) false The recipient's email address. Used for sending notifications.
recipientAccountProvider body string true The recipient's account provider.
recipientAccountNumber body string true The recipient's account number.
recipientAccountCountry body string true The country in which the recipient's account is domiciled.
statementDescriptor body string false Extra information about the disbursement.
description body string false An arbitrary string attached to the disbursement.
metadata body object false Hash of key-value pairs that you can attach to an object.
» additionalProperties body string false none

Detailed descriptions

reference: Your unique reference. If a disbursement already exists with this reference, the request will fail with 409 status code and ErrorCode will be set to duplicate_reference. For better resiliency, set the X-IDEMPOTENCY-KEY header to this as well.

amount: A positive integer in the smallest currency unit (e.g. 100 pesewas to disbursement 1.00GHS) representing how much to disbursement. The minimum amount is 100 (1.00GHS).

currency: Three-letter ISO currency code, in uppercase. Must be a supported currency. Supported currencies: GHS.

statementDescriptor: Extra information about the disbursement. This will appear on the customer’s statement. Maximum length: 22 characters.

description: An arbitrary string attached to the disbursement. Displayed in the dashboard and to customers e.g. in receipts and invoices.

metadata: Hash of key-value pairs that you can attach to an object. This is useful for storing additional information about the object in a structured format. Ideal for storing correlating information such as your internal Order Number or for tracking actions, such as detailing refunds and reasons. e.g. {"order_id": "order12345", "refunded": "Full amount", "refund_reason": "out of stock"}

Example responses

200 Response

{
  "object": "string",
  "id": "string",
  "reference": "string",
  "amount": 0,
  "fee": 0,
  "currency": "string",
  "recipientName": "string",
  "recipientEmail": "string",
  "recipientAccountProvider": "string",
  "recipientAccountNumber": "string",
  "recipientAccountCountry": "string",
  "statementDescriptor": "string",
  "description": "string",
  "paid": true,
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "receiptId": "string",
  "receiptEmail": "string",
  "receiptPhone": "string",
  "failureCode": "None",
  "failureMessage": "string",
  "state": "Pending",
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Responses

Status Meaning Description Schema
200 OK The Disbursement object DisbursementDTO
400 Bad Request Bad Request ErrorResponse
409 Conflict Conflict ErrorResponse

Fetch a Disbursement

Code samples

curl --request GET \
  --url https://api.fayapay.io/v1/Disbursements/string \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}'

GET /v1/Disbursements/{DisbursementId}

Parameters

Name In Type Required Description
DisbursementId path string true The id of the disbursement

Example responses

200 Response

{
  "object": "string",
  "id": "string",
  "reference": "string",
  "amount": 0,
  "fee": 0,
  "currency": "string",
  "recipientName": "string",
  "recipientEmail": "string",
  "recipientAccountProvider": "string",
  "recipientAccountNumber": "string",
  "recipientAccountCountry": "string",
  "statementDescriptor": "string",
  "description": "string",
  "paid": true,
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "receiptId": "string",
  "receiptEmail": "string",
  "receiptPhone": "string",
  "failureCode": "None",
  "failureMessage": "string",
  "state": "Pending",
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Responses

Status Meaning Description Schema
200 OK The Disbursement object DisbursementDTO

Update a Disbursement

Code samples

curl --request POST \
  --url https://api.fayapay.io/v1/Disbursements/ \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}' \
  --header 'content-type: application/json-patch+json' \
  --data '{"description":"string","metadata":{"property1":"string","property2":"string"}}'

POST /v1/Disbursements/{DisbursementId}

Updating is a patch operation. Only set the keys of the properties you wish to update. Properties with null values are ignored.

Body parameter

{
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Parameters

Name In Type Required Description
disbursementId path string true The id of the disbursement
body body UpdateDisbursementRequest true The update request
description body string false An arbitrary string attached to the disbursement.
metadata body object false Hash of key-value pairs that you can attach to an object.
» additionalProperties body string false none

Detailed descriptions

description: An arbitrary string attached to the disbursement. Displayed in the dashboard and to customers e.g. in receipts and invoices.

metadata: Hash of key-value pairs that you can attach to an object. This is useful for storing additional information about the object in a structured format. Ideal for storing correlating information such as your internal Order Number or for tracking actions, such as detailing refunds and reasons. e.g. {"order_id": "order12345", "refunded": "Full amount", "refund_reason": "out of stock"} Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty hash.

Example responses

200 Response

{
  "object": "string",
  "id": "string",
  "reference": "string",
  "amount": 0,
  "fee": 0,
  "currency": "string",
  "recipientName": "string",
  "recipientEmail": "string",
  "recipientAccountProvider": "string",
  "recipientAccountNumber": "string",
  "recipientAccountCountry": "string",
  "statementDescriptor": "string",
  "description": "string",
  "paid": true,
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "receiptId": "string",
  "receiptEmail": "string",
  "receiptPhone": "string",
  "failureCode": "None",
  "failureMessage": "string",
  "state": "Pending",
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Responses

Status Meaning Description Schema
200 OK The Disbursement object DisbursementDTO
400 Bad Request Bad Request ErrorResponse

Payouts

List Payouts

Code samples

curl --request GET \
  --url https://api.fayapay.io/v1/Payouts \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}'

GET /v1/Payouts

Parameters

Name In Type Required Description
EndingBefore query string false A cursor for use in pagination.
StartingAfter query string false A cursor for use in pagination.
Limit query integer(int32) false A limit on the number of objects to be returned, between 1 and 50. Defaults to 10.

Detailed descriptions

EndingBefore: A cursor for use in pagination. EndingBefore is an object ID that defines your place in the list. Specifying EndingBefore will load all objects that were created before the object you specified. For instance, if you make a list request and receive 50 objects, starting with obj_foo, your subsequent call can include EndingBefore=obj_foo in order to fetch the previous page of the list.

StartingAfter: A cursor for use in pagination. StartingAfter is an object ID that defines your place in the list. Specifying StartingAfter will load all objects that were created after the object you specified. For instance, if you make a list request and receive 50 objects, ending with obj_foo, your subsequent call can include StartingAfter=obj_foo in order to fetch the next page of the list.

Example responses

200 Response

{
  "object": "string",
  "data": [
    {
      "object": "string",
      "id": "string",
      "reference": "string",
      "amount": 0,
      "currency": "string",
      "settlementAccountProvider": "string",
      "settlementAccountNumber": "string",
      "createdAt": "2019-06-17T16:06:13Z"
    }
  ],
  "nextCursor": "string",
  "previousCursor": "string"
}

Responses

Status Meaning Description Schema
200 OK The list of Payout objects ListResponseOfPayoutDTO

Fetch a Payout

Code samples

curl --request GET \
  --url https://api.fayapay.io/v1/Payouts/string \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}'

GET /v1/Payouts/{Id}

Parameters

Name In Type Required Description
Id path string true The id of the payout

Example responses

200 Response

{
  "object": "string",
  "id": "string",
  "reference": "string",
  "amount": 0,
  "currency": "string",
  "settlementAccountProvider": "string",
  "settlementAccountNumber": "string",
  "createdAt": "2019-06-17T16:06:13Z"
}

Responses

Status Meaning Description Schema
200 OK The Payout object PayoutDTO

Refunds

List Refunds

Code samples

curl --request GET \
  --url https://api.fayapay.io/v1/Refunds \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}'

GET /v1/Refunds

Parameters

Name In Type Required Description
EndingBefore query string false A cursor for use in pagination.
StartingAfter query string false A cursor for use in pagination.
Limit query integer(int32) false A limit on the number of objects to be returned, between 1 and 50. Defaults to 10.

Detailed descriptions

EndingBefore: A cursor for use in pagination. EndingBefore is an object ID that defines your place in the list. Specifying EndingBefore will load all objects that were created before the object you specified. For instance, if you make a list request and receive 50 objects, starting with obj_foo, your subsequent call can include EndingBefore=obj_foo in order to fetch the previous page of the list.

StartingAfter: A cursor for use in pagination. StartingAfter is an object ID that defines your place in the list. Specifying StartingAfter will load all objects that were created after the object you specified. For instance, if you make a list request and receive 50 objects, ending with obj_foo, your subsequent call can include StartingAfter=obj_foo in order to fetch the next page of the list.

Example responses

200 Response

{
  "object": "string",
  "data": [
    {
      "object": "string",
      "id": "string",
      "reference": "string",
      "chargeId": "string",
      "amount": 0,
      "currency": "string",
      "description": "string",
      "metadata": {
        "property1": "string",
        "property2": "string"
      },
      "failureCode": "None",
      "failureMessage": "string",
      "state": "Pending",
      "livemode": true,
      "createdAt": "2019-06-17T16:06:13Z"
    }
  ],
  "nextCursor": "string",
  "previousCursor": "string"
}

Responses

Status Meaning Description Schema
200 OK The list of Refund objects ListResponseOfRefundDTO
400 Bad Request Bad Request ErrorResponse

Fetch a Refund

Code samples

curl --request GET \
  --url https://api.fayapay.io/v1/Refunds/string \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}'

GET /v1/Refunds/{RefundId}

Parameters

Name In Type Required Description
RefundId path string true The id of the refund

Example responses

200 Response

{
  "object": "string",
  "id": "string",
  "reference": "string",
  "chargeId": "string",
  "amount": 0,
  "currency": "string",
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "failureCode": "None",
  "failureMessage": "string",
  "state": "Pending",
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Responses

Status Meaning Description Schema
200 OK The Refund object RefundDTO

Update a Refund

Code samples

curl --request POST \
  --url https://api.fayapay.io/v1/Refunds/ \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}' \
  --header 'content-type: application/json-patch+json' \
  --data '{"description":"string","metadata":{"property1":"string","property2":"string"}}'

POST /v1/Refunds/{RefundId}

Updating is a patch operation. Only set the keys of the properties you wish to update. Properties with null values are ignored.

Body parameter

{
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Parameters

Name In Type Required Description
refundId path string true The id of the refund
body body UpdateRefundRequest true The update request
description body string false An arbitrary string attached to the refund.
metadata body object false Hash of key-value pairs that you can attach to an object.
» additionalProperties body string false none

Detailed descriptions

description: An arbitrary string attached to the refund. Displayed in the dashboard and to customers e.g. in receipts and invoices.

metadata: Hash of key-value pairs that you can attach to an object. This is useful for storing additional information about the object in a structured format. Ideal for storing correlating information such as your internal Order Number or for tracking actions, such as detailing refunds and reasons. e.g. {"order_id": "order12345", "refunded": "Full amount", "refund_reason": "out of stock"} Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty hash.

Example responses

200 Response

{
  "object": "string",
  "id": "string",
  "reference": "string",
  "chargeId": "string",
  "amount": 0,
  "currency": "string",
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "failureCode": "None",
  "failureMessage": "string",
  "state": "Pending",
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Responses

Status Meaning Description Schema
200 OK The Refund object RefundDTO
400 Bad Request Bad Request ErrorResponse

Sources

Fetch a Source

Code samples

curl --request GET \
  --url https://api.fayapay.io/v1/Sources/string \
  --header 'accept: application/json' \
  --header 'authorization: {{ API KEY }}'

GET /v1/Sources/{SourceId}

Parameters

Name In Type Required Description
SourceId path string true The id of the source

Example responses

200 Response

{
  "object": "string",
  "id": "string",
  "customerId": "string",
  "maskedName": "string",
  "currency": "string",
  "amount": 0,
  "statementDescriptor": "string",
  "type": "string",
  "useType": "Single",
  "flow": "None",
  "owner": {
    "name": "string",
    "email": "string",
    "phone": "string",
    "verifiedName": "string",
    "verifiedEmail": "string",
    "verifiedPhone": "string"
  },
  "returnUrl": "string",
  "clientSecret": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "redirectUrl": "string",
  "state": "Pending",
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Responses

Status Meaning Description Schema
200 OK The Source object SourceDTO

Schemas

ListResponseOfChargeDTO

{
  "object": "string",
  "data": [
    {
      "object": "string",
      "id": "string",
      "reference": "string",
      "sourceId": "string",
      "customerId": "string",
      "amount": 0,
      "amountRefunded": 0,
      "fee": 0,
      "currency": "string",
      "statementDescriptor": "string",
      "description": "string",
      "paid": true,
      "metadata": {
        "property1": "string",
        "property2": "string"
      },
      "receiptId": "string",
      "receiptEmail": "string",
      "receiptPhone": "string",
      "failureCode": "None",
      "failureMessage": "string",
      "state": "Pending",
      "livemode": true,
      "createdAt": "2019-06-17T16:06:13Z"
    }
  ],
  "nextCursor": "string",
  "previousCursor": "string"
}

Properties

Name Type Required Restrictions Description
object string false none none
data [ChargeDTO] false none none
nextCursor string false none none
previousCursor string false none none

ChargeDTO

{
  "object": "string",
  "id": "string",
  "reference": "string",
  "sourceId": "string",
  "customerId": "string",
  "amount": 0,
  "amountRefunded": 0,
  "fee": 0,
  "currency": "string",
  "statementDescriptor": "string",
  "description": "string",
  "paid": true,
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "receiptId": "string",
  "receiptEmail": "string",
  "receiptPhone": "string",
  "failureCode": "None",
  "failureMessage": "string",
  "state": "Pending",
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Properties

Name Type Required Restrictions Description
object string false none String representing the object’s type. Objects of the same type share the same value. Value is charge
id string false none Unique identifier for the object.
reference string false none Unique reference you provided.
sourceId string false none ID of the source that was charged.
customerId string false none ID of the customer this charge belongs to if one exists.
amount integer(int32) true none A positive integer in the smallest currency unit (e.g. 100 pesewas to charge 1.00GHS) representing how much was charged.
amountRefunded integer(int32) true none An integer in the smallest currency unit (e.g. 100 pesewas equals 1.00GHS) representing how much of the charge was refunded. This can be less than Amount if the refund was partial.
fee integer(int32) true none A positive integer in the smallest currency unit (e.g. 100 pesewas to charge 1.00GHS) representing how much was charged as fees.
currency string false none Three-letter ISO currency code. e.g. GHS
statementDescriptor string false none Extra information about the charge. This appears on your customer’s statement.
description string false none An arbitrary string attached to the charge. Mainly useful for displaying to customers e.g. in receipts and invoices.
paid boolean true none true if the charge succeeded, or was successfully authorized for later capture.
metadata object false none Hash of key-value pairs attached to the object.
» additionalProperties string false none none
receiptId string false none ID for the receipt sent for this charge. This attribute will be null until a receipt has been sent.
receiptEmail string false none This is the email address that the receipt for this charge was sent to. This attribute will be null until a receipt has been sent.
receiptPhone string false none This is the phone number that the receipt for this charge was sent to. This attribute will be null until a receipt has been sent.
failureCode ChargeFailureCodeValue true none Detailed failure code if the state of the charge is Failed.
failureMessage string false none Detailed failure message if the state of the charge is Failed. Can be displayed to the user.
state ChargeStateValue true none The state of the charge.
livemode boolean true none true if the object exists in live mode or false if the object exists in test mode.
createdAt string(date-time) true none Time at which the object was created.

ChargeFailureCodeValue

"None"

Properties

Name Type Required Restrictions Description
anonymous string false none none

Enumerated Values

Property Value
anonymous None
anonymous UserDeclined
anonymous InsufficientBalance
anonymous TimedOut

ChargeStateValue

"Pending"

Properties

Name Type Required Restrictions Description
anonymous string false none none

Enumerated Values

Property Value
anonymous Pending
anonymous Succeeded
anonymous Failed
anonymous Refunded

ErrorResponse

{
  "object": "string",
  "code": "string",
  "messages": [
    "string"
  ]
}

Properties

Name Type Required Restrictions Description
object string false none String representing the object’s type. Objects of the same type share the same value. Value is error
code string false none The error code general_error: non-specific error authentication_error: failed to authenticate your request. invalid or missing api key authorization_error: failed to authorize your request. missing permission or failed kyc check validation_error: an error occurred while validating your request livemode_mismatch: an object is being accessed with an api key of a different livemode duplicate_reference: supplied reference has already been used idempotency_error: supplied idempotency key has already been used with a different request source_expired: specified source has expired currency_mismatch: specified currency does not match source currency amount_mismatch: specified amount does not match source amount
messages [string] false none List of error messages

CreateChargeRequest

{
  "reference": "string",
  "source": "string",
  "customer": "string",
  "amount": 0,
  "currency": "str",
  "statementDescriptor": "string",
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Properties

Name Type Required Restrictions Description
reference string true none Your unique reference. If a charge already exists with this reference, the request will fail with 409 status code and ErrorCode will be set to duplicate_reference. For better resiliency, set the X-IDEMPOTENCY-KEY header to this as well.
source string false none The ID of the source to charge. If the source is not attached to a customer, it is consumed.
customer string false none The ID of the customer to charge. If Source is not specified, the default customer source is charged. If an unattached source is specified, this will only associate the customer with the charge however, the source is still consumed.
amount integer(int32) true none A positive integer in the smallest currency unit (e.g. 100 pesewas to charge 1.00GHS) representing how much to charge. The minimum amount is 100 (1.00GHS).
currency string true none Three-letter ISO currency code, in uppercase. Must be a supported currency. Supported currencies: GHS.
statementDescriptor string false none Extra information about the charge. This will appear on the customer’s statement. Maximum length: 22 characters.
description string false none An arbitrary string attached to the charge. Displayed in the dashboard and to customers e.g. in receipts and invoices.
metadata object false none Hash of key-value pairs that you can attach to an object. This is useful for storing additional information about the object in a structured format. Ideal for storing correlating information such as your internal Order Number or for tracking actions, such as detailing refunds and reasons. e.g. {"order_id": "order12345", "refunded": "Full amount", "refund_reason": "out of stock"}
» additionalProperties string false none none

UpdateChargeRequest

{
  "customer": "string",
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Properties

Name Type Required Restrictions Description
customer string false none The ID of an existing customer that will be associated with this request. This field may only be updated if there is no existing associated customer with this charge. If already associated, the request will fail.
description string false none An arbitrary string attached to the charge. Displayed in the dashboard and to customers e.g. in receipts and invoices.
metadata object false none Hash of key-value pairs that you can attach to an object. This is useful for storing additional information about the object in a structured format. Ideal for storing correlating information such as your internal Order Number or for tracking actions, such as detailing refunds and reasons. e.g. {"order_id": "order12345", "refunded": "Full amount", "refund_reason": "out of stock"} Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty hash.
» additionalProperties string false none none

RefundChargeRequest

{
  "reference": "string",
  "amount": 0,
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Properties

Name Type Required Restrictions Description
reference string true none Your unique reference. If a refund already exists with this reference, the request will fail with 409 status code and ErrorCode will be set to duplicate_reference. For better resiliency, set the X-IDEMPOTENCY-KEY header to this as well.
amount integer(int32) false none A positive integer in the smallest currency unit (e.g. 100 pesewas to charge 1.00GHS) representing how much to refund. The minimum amount is 100 (1.00GHS). Omit to issue a full refund. Must not exceed the original charge amount.
description string false none An arbitrary string attached to the refund. Displayed in the dashboard and to customers e.g. in receipts and invoices.
metadata object false none Hash of key-value pairs that you can attach to an object. This is useful for storing additional information about the object in a structured format. Ideal for storing correlating information such as your internal Order Number or for tracking actions, such as detailing refunds and reasons. e.g. {"order_id": "order12345", "refunded": "Full amount", "refund_reason": "out of stock"}
» additionalProperties string false none none

RefundDTO

{
  "object": "string",
  "id": "string",
  "reference": "string",
  "chargeId": "string",
  "amount": 0,
  "currency": "string",
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "failureCode": "None",
  "failureMessage": "string",
  "state": "Pending",
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Properties

Name Type Required Restrictions Description
object string false none String representing the object’s type. Objects of the same type share the same value. Value is refund
id string false none Unique identifier for the object.
reference string false none Unique reference you provided.
chargeId string false none ID of the charge that was refunded.
amount integer(int32) true none A positive integer in the smallest currency unit (e.g. 100 pesewas to refund 1.00GHS) representing how much was refunded.
currency string false none Three-letter ISO currency code. e.g. GHS
description string false none An arbitrary string attached to the refund. Mainly useful for displaying to customers e.g. in email notifications.
metadata object false none Hash of key-value pairs attached to the refund.
» additionalProperties string false none none
failureCode RefundFailureCodeValue true none Detailed failure code if the state of the refund is Failed.
failureMessage string false none Detailed failure message if the state of the refund is Failed. Can be displayed to the user.
state RefundStateValue true none The state of the refund.
livemode boolean true none true if the object exists in live mode or false if the object exists in test mode.
createdAt string(date-time) true none Time at which the object was created.

RefundFailureCodeValue

"None"

Properties

Name Type Required Restrictions Description
anonymous string false none none

Enumerated Values

Property Value
anonymous None
anonymous GatewayError
anonymous UnableToProcess
anonymous ClaimTokenExpired

RefundStateValue

"Pending"

Properties

Name Type Required Restrictions Description
anonymous string false none none

Enumerated Values

Property Value
anonymous Pending
anonymous Succeeded
anonymous Failed

ListResponseOfCustomerDTO

{
  "object": "string",
  "data": [
    {
      "object": "string",
      "id": "string",
      "name": "string",
      "email": "string",
      "phone": "string",
      "description": "string",
      "metadata": {
        "property1": "string",
        "property2": "string"
      },
      "livemode": true,
      "createdAt": "2019-06-17T16:06:13Z"
    }
  ],
  "nextCursor": "string",
  "previousCursor": "string"
}

Properties

Name Type Required Restrictions Description
object string false none none
data [CustomerDTO] false none none
nextCursor string false none none
previousCursor string false none none

CustomerDTO

{
  "object": "string",
  "id": "string",
  "name": "string",
  "email": "string",
  "phone": "string",
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Properties

Name Type Required Restrictions Description
object string false none String representing the object’s type. Objects of the same type share the same value. Value is customer
id string false none Unique identifier for the object.
name string false none The fullname of the customer
email string false none The email of the customer.
phone string false none The phone number of the customer.
description string false none An arbitrary string attached to the customer.
metadata object false none Hash of key-value pairs attached to the object.
» additionalProperties string false none none
livemode boolean true none true if the object exists in live mode or false if the object exists in test mode.
createdAt string(date-time) true none Time at which the object was created.

CreateCustomerRequest

{
  "name": "string",
  "email": "user@example.com",
  "phone": "string",
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Properties

Name Type Required Restrictions Description
name string true none The Name of the customer.
email string(email) false none An optional email for the customer. Used by FayaPay to send receipts and notifications.
phone string false none An optional phone number for the customer. Used by FayaPay to send receipts and notifications. If set, phone must be a valid phone number, including the country code e.g. +233200123456
description string false none An arbitrary string attached to the customer. Displayed in the dashboard.
metadata object false none Hash of key-value pairs that you can attach to an object. This is useful for storing additional information about the object in a structured format. Ideal for storing additional information such as the customer's address. e.g. {"city": "Accra", "country": "customer_country", "address_line": "address"}
» additionalProperties string false none none

UpdateCustomerRequest

{
  "name": "string",
  "email": "user@example.com",
  "phone": "string",
  "description": "string",
  "defaultSource": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Properties

Name Type Required Restrictions Description
name string false none The Name of the customer.
email string(email) false none An optional email for the customer. Used by FayaPay to send receipts and notifications.
phone string false none An optional phone number for the customer. Used by FayaPay to send receipts and notifications. If set, phone must be a valid phone number, including the country code e.g. +233200123456
description string false none An arbitrary string attached to the customer. Displayed in the dashboard.
defaultSource string false none Id of the Source to set as customer's default.
metadata object false none Hash of key-value pairs that you can attach to an object. This is useful for storing additional information about the object in a structured format. Ideal for storing additional information such as the customer's address. e.g. {"city": "Accra", "country": "customer_country", "address_line": "address"}
» additionalProperties string false none none

AttachSourceRequest

{
  "source": "string"
}

Properties

Name Type Required Restrictions Description
source string true none Id of the Source to attach to the customer.

SourceDTO

{
  "object": "string",
  "id": "string",
  "customerId": "string",
  "maskedName": "string",
  "currency": "string",
  "amount": 0,
  "statementDescriptor": "string",
  "type": "string",
  "useType": "Single",
  "flow": "None",
  "owner": {
    "name": "string",
    "email": "string",
    "phone": "string",
    "verifiedName": "string",
    "verifiedEmail": "string",
    "verifiedPhone": "string"
  },
  "returnUrl": "string",
  "clientSecret": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "redirectUrl": "string",
  "state": "Pending",
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Properties

Name Type Required Restrictions Description
object string false none String representing the object’s type. Objects of the same type share the same value. Value is source
id string false none Unique identifier for the object.
customerId string false none ID of the customer this source is attached to.
maskedName string false none Masked name for this source. Can be displayed publicly.
currency string false none Three-letter ISO currency code. e.g. GHS
amount integer(int32) true none A positive integer in the smallest currency unit (e.g. 100 pesewas to charge 1.00GHS) representing how much you intend to charge.
statementDescriptor string false none Extra information about the charge. This appears on your customer’s statement.
type string false none The type of the source is momo.
useType PaymentChannelUseTypeValue true none The use type of the source.
flow PaymentChannelCreationFlowValue true none Additional action that needs to be taken to complete the source creation. When value is Redirect, redirect the user to the RedirectUrl. After source creation is complete, the user will be sent back to your site. The Source Id will be passed in the query string via the fayapay_source_id parameter.
owner SourceOwnerDTO false none The details of the owner of this source.
returnUrl string false none The url to return your users to after a redirect.
clientSecret string false none When Flow is Redirect, when client is being redirected back to your site after source creation, this will be passed in the query string via the fayapay_client_secret parameter. You may use this to verify the client.
metadata object false none Hash of key-value pairs attached to the object.
» additionalProperties string false none none
redirectUrl string false none When Flow is Redirect, redirect the customer in order to complete source creation
state SourceStateValue true none The state of the source.
livemode boolean true none true if the object exists in live mode or false if the object exists in test mode.
createdAt string(date-time) true none Time at which the object was created.

PaymentChannelUseTypeValue

"Single"

Properties

Name Type Required Restrictions Description
anonymous string false none none

Enumerated Values

Property Value
anonymous Single
anonymous Reuseable

PaymentChannelCreationFlowValue

"None"

Properties

Name Type Required Restrictions Description
anonymous string false none none

Enumerated Values

Property Value
anonymous None
anonymous Redirect
anonymous InputCode
anonymous ScanCode
anonymous Receiver

SourceOwnerDTO

{
  "name": "string",
  "email": "string",
  "phone": "string",
  "verifiedName": "string",
  "verifiedEmail": "string",
  "verifiedPhone": "string"
}

Properties

Name Type Required Restrictions Description
name string false none none
email string false none none
phone string false none none
verifiedName string false none none
verifiedEmail string false none none
verifiedPhone string false none none

SourceStateValue

"Pending"

Properties

Name Type Required Restrictions Description
anonymous string false none none

Enumerated Values

Property Value
anonymous Pending
anonymous Chargeable
anonymous Consumed
anonymous Canceled
anonymous Failed
anonymous Expired

ListResponseOfDisbursementDTO

{
  "object": "string",
  "data": [
    {
      "object": "string",
      "id": "string",
      "reference": "string",
      "amount": 0,
      "fee": 0,
      "currency": "string",
      "recipientName": "string",
      "recipientEmail": "string",
      "recipientAccountProvider": "string",
      "recipientAccountNumber": "string",
      "recipientAccountCountry": "string",
      "statementDescriptor": "string",
      "description": "string",
      "paid": true,
      "metadata": {
        "property1": "string",
        "property2": "string"
      },
      "receiptId": "string",
      "receiptEmail": "string",
      "receiptPhone": "string",
      "failureCode": "None",
      "failureMessage": "string",
      "state": "Pending",
      "livemode": true,
      "createdAt": "2019-06-17T16:06:13Z"
    }
  ],
  "nextCursor": "string",
  "previousCursor": "string"
}

Properties

Name Type Required Restrictions Description
object string false none none
data [DisbursementDTO] false none none
nextCursor string false none none
previousCursor string false none none

DisbursementDTO

{
  "object": "string",
  "id": "string",
  "reference": "string",
  "amount": 0,
  "fee": 0,
  "currency": "string",
  "recipientName": "string",
  "recipientEmail": "string",
  "recipientAccountProvider": "string",
  "recipientAccountNumber": "string",
  "recipientAccountCountry": "string",
  "statementDescriptor": "string",
  "description": "string",
  "paid": true,
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "receiptId": "string",
  "receiptEmail": "string",
  "receiptPhone": "string",
  "failureCode": "None",
  "failureMessage": "string",
  "state": "Pending",
  "livemode": true,
  "createdAt": "2019-06-17T16:06:13Z"
}

Properties

Name Type Required Restrictions Description
object string false none String representing the object’s type. Objects of the same type share the same value. Value is disbursement
id string false none Unique identifier for the object.
reference string false none Unique reference you provided.
amount integer(int32) true none A positive integer in the smallest currency unit (e.g. 100 pesewas to disburse 1.00GHS) representing how much was disbursed.
fee integer(int32) true none A positive integer in the smallest currency unit (e.g. 100 pesewas to charge 1.00GHS) representing how much was charged as fees.
currency string false none Three-letter ISO currency code. e.g. GHS
recipientName string false none The recipient's name.
recipientEmail string false none The recipient's email address. Used for sending notifications.
recipientAccountProvider string false none The recipient's account provider.
recipientAccountNumber string false none The recipient's account number.
recipientAccountCountry string false none The country in which the recipient's account is domiciled.
statementDescriptor string false none Extra information about the disbursement. This appears on your customer’s statement.
description string false none An arbitrary string attached to the disbursement. Mainly useful for displaying to customers e.g. in receipts and invoices.
paid boolean true none true if the disbursement succeeded.
metadata object false none Hash of key-value pairs attached to the object.
» additionalProperties string false none none
receiptId string false none ID for the receipt sent for this disbursement. This attribute will be null until a receipt has been sent.
receiptEmail string false none This is the email address that the receipt for this disbursement was sent to. This attribute will be null until a receipt has been sent.
receiptPhone string false none This is the phone number that the receipt for this disbursement was sent to. This attribute will be null until a receipt has been sent.
failureCode DisbursementFailureCodeValue true none Detailed failure code if the state of the disbursement is Failed.
failureMessage string false none Detailed failure message if the state of the disbursement is Failed. May not be appropriate to display to the user as it may include information about your account.
state DisbursementStateValue true none The state of the disbursement.
livemode boolean true none true if the object exists in live mode or false if the object exists in test mode.
createdAt string(date-time) true none Time at which the object was created.

DisbursementFailureCodeValue

"None"

Properties

Name Type Required Restrictions Description
anonymous string false none none

Enumerated Values

Property Value
anonymous None
anonymous GatewayError
anonymous InsufficientBalance
anonymous TimedOut

DisbursementStateValue

"Pending"

Properties

Name Type Required Restrictions Description
anonymous string false none none

Enumerated Values

Property Value
anonymous Pending
anonymous Succeeded
anonymous Failed

CreateDisbursementRequest

{
  "reference": "string",
  "amount": 0,
  "currency": "str",
  "recipientName": "string",
  "recipientEmail": "user@example.com",
  "recipientAccountProvider": "string",
  "recipientAccountNumber": "string",
  "recipientAccountCountry": "string",
  "statementDescriptor": "string",
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Properties

Name Type Required Restrictions Description
reference string true none Your unique reference. If a disbursement already exists with this reference, the request will fail with 409 status code and ErrorCode will be set to duplicate_reference. For better resiliency, set the X-IDEMPOTENCY-KEY header to this as well.
amount integer(int32) true none A positive integer in the smallest currency unit (e.g. 100 pesewas to disbursement 1.00GHS) representing how much to disbursement. The minimum amount is 100 (1.00GHS).
currency string true none Three-letter ISO currency code, in uppercase. Must be a supported currency. Supported currencies: GHS.
recipientName string false none The recipient's name.
recipientEmail string(email) false none The recipient's email address. Used for sending notifications.
recipientAccountProvider string true none The recipient's account provider.
recipientAccountNumber string true none The recipient's account number.
recipientAccountCountry string true none The country in which the recipient's account is domiciled.
statementDescriptor string false none Extra information about the disbursement. This will appear on the customer’s statement. Maximum length: 22 characters.
description string false none An arbitrary string attached to the disbursement. Displayed in the dashboard and to customers e.g. in receipts and invoices.
metadata object false none Hash of key-value pairs that you can attach to an object. This is useful for storing additional information about the object in a structured format. Ideal for storing correlating information such as your internal Order Number or for tracking actions, such as detailing refunds and reasons. e.g. {"order_id": "order12345", "refunded": "Full amount", "refund_reason": "out of stock"}
» additionalProperties string false none none

UpdateDisbursementRequest

{
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Properties

Name Type Required Restrictions Description
description string false none An arbitrary string attached to the disbursement. Displayed in the dashboard and to customers e.g. in receipts and invoices.
metadata object false none Hash of key-value pairs that you can attach to an object. This is useful for storing additional information about the object in a structured format. Ideal for storing correlating information such as your internal Order Number or for tracking actions, such as detailing refunds and reasons. e.g. {"order_id": "order12345", "refunded": "Full amount", "refund_reason": "out of stock"} Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty hash.
» additionalProperties string false none none

ListResponseOfPayoutDTO

{
  "object": "string",
  "data": [
    {
      "object": "string",
      "id": "string",
      "reference": "string",
      "amount": 0,
      "currency": "string",
      "settlementAccountProvider": "string",
      "settlementAccountNumber": "string",
      "createdAt": "2019-06-17T16:06:13Z"
    }
  ],
  "nextCursor": "string",
  "previousCursor": "string"
}

Properties

Name Type Required Restrictions Description
object string false none none
data [PayoutDTO] false none none
nextCursor string false none none
previousCursor string false none none

PayoutDTO

{
  "object": "string",
  "id": "string",
  "reference": "string",
  "amount": 0,
  "currency": "string",
  "settlementAccountProvider": "string",
  "settlementAccountNumber": "string",
  "createdAt": "2019-06-17T16:06:13Z"
}

Properties

Name Type Required Restrictions Description
object string false none String representing the object’s type. Objects of the same type share the same value. Value is payout
id string false none Unique identifier for the object.
reference string false none A unique reference string
amount integer(int32) true none An integer in the smallest currency unit (e.g. 100 pesewas = 1.00GHS) representing how much was paid out.
currency string false none Three-letter ISO currency code. e.g. GHS.
settlementAccountProvider string false none The settlement account provider. e.g. GCB, CBG.
settlementAccountNumber string false none The settlement account number.
createdAt string(date-time) true none Time at which the object was created.

ListResponseOfRefundDTO

{
  "object": "string",
  "data": [
    {
      "object": "string",
      "id": "string",
      "reference": "string",
      "chargeId": "string",
      "amount": 0,
      "currency": "string",
      "description": "string",
      "metadata": {
        "property1": "string",
        "property2": "string"
      },
      "failureCode": "None",
      "failureMessage": "string",
      "state": "Pending",
      "livemode": true,
      "createdAt": "2019-06-17T16:06:13Z"
    }
  ],
  "nextCursor": "string",
  "previousCursor": "string"
}

Properties

Name Type Required Restrictions Description
object string false none none
data [RefundDTO] false none none
nextCursor string false none none
previousCursor string false none none

UpdateRefundRequest

{
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Properties

Name Type Required Restrictions Description
description string false none An arbitrary string attached to the refund. Displayed in the dashboard and to customers e.g. in receipts and invoices.
metadata object false none Hash of key-value pairs that you can attach to an object. This is useful for storing additional information about the object in a structured format. Ideal for storing correlating information such as your internal Order Number or for tracking actions, such as detailing refunds and reasons. e.g. {"order_id": "order12345", "refunded": "Full amount", "refund_reason": "out of stock"} Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty hash.
» additionalProperties string false none none