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.

2xx indicate success.
4xx indicate a problem with the information you sent in your request (e.g., a validation error occurred, etc.).
5xx indicate an error with our servers (these are rare).

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.

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.

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

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

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.

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.

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

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

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.

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