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.
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. |
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. |
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 |
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. |
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. |
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 |
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 |