FundRequest

Introducing

Materializing a request for funds, a collection, this object contains a collection link as well as a QRCode that can be scanned using a smartphone's camera. Once created, you can access the encashment link via the securePay.link field, and you can access the url pointing to the QRCode image via the securePay.qrCode.src field.
You can control the message displayed to the user by submitting a value for the h1 field when creating the FundRequest object. If you add 2 languages, the user will be able to change language and see the message inviting him to pay in his native language.
Once you've sent this link to your user, or presented them with the QRCode, they'll be taken to a page inviting them to pay, as shown in the following figure: FPay FundRequest Fr

Operations

`cancel`

Cancel and then Returns an object FundRequest found by an identifier.
You can use a unique ID specific to your system. To use your own ID instead of the one generated by FPay, you need to specify the foreignId field when creating the object. This will enable you to retrieve the object via the foreignId field, which must be unique for all FundRequest objects.
Here are all the fields whose values can be used as identifiers for this operation:

id
foreignId

It is not possible to cancel a FundRequest object that has already been cancelled, either successfully or unsuccessfully.

const fundRequestPromise = fPay.fundRequest.cancel("identifier");

`create`

Create a new FundRequest object and return the newly created object.
This operation takes the following parameters as input:

CreateFundRequestForm

amount Required

AmountForm
Transaction amount without fees. If you pay the fees, you will receive in your wallet this amount minus fees. If your correspondent pays the fees, you will receive exactly this amount in your wallet.

currency Required: string
The only possible value is"XOF"

value Required: string
Numeric value of amount always positive or zero.

description: string | undefined
Details, explanations and notes about this item to help you get organized and find your way around later.

destination

DestinationForm | undefined
Destination of funds.

DestinationForm.MultipleDestinationForm
MultipleDestinationForm

DestinationForm.SingleDestinationForm
SingleDestinationForm

account Required

MoneyAccountForm
FPay Wallet which will be credited when the money is received. This value is optional and if no value is specified, the main wallet will be credited.

country Required: string
The only possible value is"CI"

identifier Required: string
FPay Wallet id identifier

providerKey Required: string
The only possible value is"FPay"

expire

string | undefined
If present, then this value indicates that this object has an expiry date and will be cancelled when it expires.
General Format

<after><space><$number><$timeUnit>
<on><space><$iso8601Datetime>
never

For FundRequest object, the value never is the default value if none specified.
For QuasiTransfer object, the value 24h is the default value if none specified.

Examples

"after 15m": The funds request will expire 15 minutes after creation
"after 90s": The funds request will expire 90 seconds after creation
"after 1h": The created object will expire 1 hour after creation
"after 2d": The created object will expire 2 days after creation
"after 1w": The created object will expire 1 week after creation
"on 2028-05-19T01:13Z": The created object will expire on May 19, 2028 at 01:13 GMT. The 'Z' at the end stands for GMT and this format is from ISO 8601.
"on 2028-05-19": The created object will expire on May 19, 2028 at 00:00 GMT
"on 15:30": The created object will expire at 15:30 GMT on the day of its creation.

fees

FeesForm | undefined

payer Required: string
Who pays the fees associated with this operation ? If no costs are involved, this value will be omitted.
The only possible values are"CounterPart" "Me" "Receiver" "Sender"

foreignData: string | undefined
Your own data that you can attach to the object you've created. This can be JSON XML other data formats or simply Strings.
The maximum allowed length is 128 characters.

foreignId: string | undefined
ID Personalisé ou bien ID de votre système interne que vous souhaitez attacher à cet objet pour vous permettre de le récupérer plus tard.
Once created, this value cannot be modified.
This value must be unique for each type.
The maximum allowed length is 128 characters.

h1

H1DescriptorForm | undefined
Title of this object, which will be displayed to the user if necessary, and which will become the h1 field of the Transaction object when it will be created.

en: string | undefined

fr: string | undefined

onFailure

OnFundRequestCompletedForm | undefined
Defines the actions to be taken by the FPAy server if this operation fails

redirectUserTo: string | undefined
Url to which the user will be redirected at the end of the operation. We recommend that you use an https url. You cannot provide an ip address or any other value in place of the domain name.

onSuccess

OnFundRequestCompletedForm | undefined
Action to be taken if this operation fails

redirectUserTo: string | undefined
Url to which the user will be redirected at the end of the operation. We recommend that you use an https url. You cannot provide an ip address or any other value in place of the domain name.

Here's an example of code for creating a FundRequest object:

const fundRequestPromise = 
    fPay.fundRequest.create({
        amount: {
            currency: "XOF",
            value: "10_000"
        },
        description: "My description",
        destination: {
            _type: "Single",
            account: {
                country: "CI",
                identifier: "123456789",
                providerKey: "FPay"
            }
        },
        expire: "after 12h",
        fees: {
            payer: "CounterPart"
        },
        foreignData: "{\"myKey\": 19, \"myOtherKey\": \"myOtherValue\"}",
        foreignId: "123456789",
        h1: {
            en: "Payment description",
            fr: "Description du paiement"
        },
        onFailure: {
            redirectUserTo: "https://you-server.com/ui/failure"
        },
        onSuccess: {
            redirectUserTo: "https://you-server.com/ui/success"
        }
    });

`get`

Returns an object FundRequest found by an identifier.
You can use a unique ID specific to your system. To use your own ID instead of the one generated by FPay, you need to specify the foreignId field when creating the object. This will enable you to retrieve the object via the foreignId field, which must be unique for all FundRequest objects. Here are all the fields whose values can be used as identifiers for this operation:

id
foreignId

const fundRequestPromise = fPay.fundRequest.get("identifier");

`list`

Returns a collection of FundRequest objects, possibly filtered and/or sorted. Here are the parameters supported by this operation.

NAME	TYPE	DESCRIPTION	DEFAULT VALUE
`filter`	string \| undefined	Condition to be met by any object returned in this collection	`undefined`
`sortBy`	string \| undefined	Specify the field and the order (ascending or descending) by which returned objects will be sorted	`createdTime:DESC`
`limit`	number \| undefined	Total number of results to return in this collection	`50`

Here are a few examples of code to execute a listing to return a collection of FundRequest objects:

const fundRequestsCollectionPromise = fPay.fundRequest.listAll();

const fundRequestsCollectionPromise = 
    fPay.fundRequest.list({
        sortBy: "id:ASC"
    });

const fundRequestsCollectionPromise = 
    fPay.fundRequest.list({
        limit: 5
    });

const fundRequestsCollectionPromise = 
    fPay.fundRequest.list({
        filter: "id in {'31234', '5678', '9990'}"
    });

const fundRequestsCollectionPromise = 
    fPay.fundRequest.list({
        filter: "createdTime isBefore Yesterday",
        sortBy: "foreignId:DESC"
    });

const fundRequestsCollectionPromise = 
    fPay.fundRequest.list({
        filter: "id startsWith abcd",
        sortBy: "createdTime:ASC",
        limit: 25
    });

`fetchPage`

When you fetch a list of FundRequest, the results returned by the server can be paginated, i.e. they will be arranged on several pages. This fetchPage function allows you to navigate from page to page, iterating over all the elements. Consequently, this function returns a collection of FundRequest.

Let's say you've retrieved a collection of FundRequest with the following code:

const fundRequestsCollectionPromise = fPay.fundRequest.listAll();

If the result is spread over several pages, to go to the next page, you should do:

fundRequestsCollectionPromise.then(fundRequestCollection => {
    if(fundRequestCollection.hasNextPage()) {
        const nextFundRequestPromise = fPay.fundRequest.fetchPage(fundRequestCollection.pagination.nextPage);
    }
});

`send`

Sends funds to a fund request identified by an identifier and returns an Attempt symbolizing an attempt to send.
Here are all the fields whose values can be used as identifiers for this operation:

id
foreignId

From the user's point of view, a call to this function triggers a collection of funds from the user's money account, in an attempt to transmit them to the FPay account that originated the fund request.
This operation takes the following parameters as input:

SendFundRequestForm

id Required: string
Unique, unchangeable identifier made up of numbers and letters.

source Required

SourceForm
Source of funds.

SourceForm.MultipleSourceForm
MultipleSourceForm

SourceForm.SingleSourceForm
SingleSourceForm

account Required

MoneyAccountForm
Mobile money account from which you would like to collect money.

country Required: string
The only possible value is"CI"

identifier Required: string
Telephone number in international "+2250500000000"

providerKey Required: string
The only possible values are"MoovMoney" "MtnMoney" "OrangeMoney"

Here's an example of code for send money in response to a FundRequest object:

const attemptPromise = 
    fPay.fundRequest.send({
        id: "123456789",
        source: {
            _type: "Single",
            account: {
                country: "CI",
                identifier: "+2250500000000",
                providerKey: "MtnMoney"
            }
        }
    });

`update`

Modify a FundRequest object and return the modified version.
Here are all the fields whose values can be used as identifiers for this operation:

id
foreignId

Modifying an object means modifying its modifiable fields. Modifiable fields can be either updated or deleted. Here's the list of modifiable fields for all FundRequest objects:

NAME	TYPE	DESCRIPTION
`description`	string \| undefined	Can be updated Can be Deleted
`foreignData`	string \| undefined	Can be updated Can be Deleted

Here are a few examples of code to execute an update:

fundRequestPromise = 
    fPay.fundRequest.update({
         id: "<id | foreignId>",
         change: {
            description: "<new value>",
            foreignData: "<new value>"
         }
    });

fundRequestPromise = 
    fPay.fundRequest.update({
         id: "<id | foreignId>",
         change: {
            description: "<new value>"
         },
         'remove': ['foreignData']
    });

fundRequestPromise = 
    fPay.fundRequest.update({
         id: "<id | foreignId>",
         'remove': ['description', 'foreignData']
    });

List Filter & Sort

Fields

When you retrieve a list, here are the fields you can use for filtering and sorting. as well as sorting.

NAME	TYPE	DESCRIPTION
`amount.currency.code`	string
`amount.value`	number
`completedTime`	string
`completedTime.iso8601`	string
`completedTime.timestamp.milliseconds`	number
`completedTime.timestamp.seconds`	number
`createdTime`	string
`createdTime.iso8601`	string
`createdTime.timestamp.milliseconds`	number
`createdTime.timestamp.seconds`	number
`creator`	string
`creator._type`	string
`creator.accountId`	string
`creator.authAccessId`	string
`creator.personId`	string
`description`	string
`destination`	string
`destination._type`	string
`destination.account.balanceType`	string
`destination.account.identifier._type`	string
`destination.account.identifier.value`	string
`destination.account.provider.country.iso3166.alpha2`	string
`destination.account.provider.country.iso3166.alpha3`	string
`destination.account.provider.country.name`	string
`destination.account.provider.key`	string
`destination.account.provider.name`	string
`destination.amount.currency.code`	string
`destination.amount.value`	number
`expire.delay`	string
`expire.time`	string
`expire.time.iso8601`	string
`expire.time.timestamp.milliseconds`	number
`expire.time.timestamp.seconds`	number
`fees.amount.currency.code`	string
`fees.amount.value`	number
`fees.payer`	string
`fees.value.fixe`	number
`fees.value.percent`	number
`foreignId`	string
`h1Descriptor.en`	string
`h1Descriptor.fr`	string
`id`	string
`onFailure.redirectUserTo`	string
`onSuccess.redirectUserTo`	string
`securePay.link`	string
`securePay.purpose.label`	string
`securePay.qrCode.src`	string
`sending`	string
`source`	string
`source._type`	string
`source.account.balanceType`	string
`source.account.identifier._type`	string
`source.account.identifier.value`	string
`source.account.provider.country.iso3166.alpha2`	string
`source.account.provider.country.iso3166.alpha3`	string
`source.account.provider.country.name`	string
`source.account.provider.key`	string
`source.account.provider.name`	string
`source.amount.currency.code`	string
`source.amount.value`	number
`status`	string
`status._type`	string
`status.cancelled.afterTimeout`	boolean
`status.reason.en`	string
`status.reason.fr`	string

Code examples

Code examples are available on the Audit & Dashboard page

Fields

FundRequest

amount

Amount | undefined

currency

AmountCurrency

code: string
The only possible value is"XOF"

unit: string
Symbol used to represent this currency. For now, the only value is "₣".

value: number
Numeric value of amount always positive or zero.

completedTime

UTCDateTime | undefined
If this value is present, then it corresponds to the date and time at which this operation ended. If it is absent, then this operation is still in progress.
Value always stored in UTC (Universal Time), this field contains a representation of this instant in ISO 8601 format, as well as a representation of this same instant in timestamp seconds and milliseconds.

iso8601: string
Date and time in ISO 8601 format

timestamp

Timestamp

milliseconds: number
Date and time in timestamp milli seconds

seconds: Double
Date and time in timestamp seconds

createdTime

UTCDateTime
Date and time at which this object was created. Value always stored in UTC (Universal Time), this field contains a representation of this instant in ISO 8601 format, as well as a representation of this same instant in timestamp seconds and milliseconds.

iso8601: string
Date and time in ISO 8601 format

timestamp

Timestamp

milliseconds: number
Date and time in timestamp milli seconds

seconds: Double
Date and time in timestamp seconds

creator

Creator

Creator.Api
Api

_type: string
The only possible value is"Api"

accountId: string

authAccessId: string

Creator.Ui
Ui

_type: string
The only possible value is"Ui"

accountId: string

personId: string

description: string | undefined
Details, explanations and notes about this item to help you get organized and find your way around later.

destination

Destination

Destination.Multiple
Multiple

_type: string
The only possible value is"Multiple"

Destination.Single
Single

_type: string
The only possible value is"Single"

account

MoneyAccount

balanceType: string
Indicates the type of balance used.
"AvailableBalance" literally means “Available Balance”. So, if the value of this field is “AvailableBalance”, then the funds are on the "AvailableBalance" and can be used. In some cases, funds are “Locked” (either on the "LockedInBalance" or "LockedOutBalance" ) and cannot be used until they are made available on the "AvailableBalance".
The only possible values are"AvailableBalance" "LockedInBalance" "LockedOutBalance"

identifier

MoneyAccountIdentifier

_type: string
Indicates the type of account on which “MoneyAccount” money is held. If it's a bank account, this field will have the value "Iban".
If it's a mobile money account, this field will have the value "MobileMoney".
If it's an FPay wallet, the value can be either "Id" or "Man", the latter meaning "Money Account Number".
The only possible values are"Iban" "Id" "Man" "MobileNumber"

value: string
Indicates the type of account on which “MoneyAccount” money is held. If it's a bank account, this field will have the value "Iban".
If it's a mobile money account, this field will have the value "MobileMoney".
If it's an FPay account, the value can be either "Id" or "Man", the latter meaning "Money Account Number".

provider

MoneyAccountProvider

country

Country

iso3166

Iso3166Country

alpha2: string
ISO 3166 code with 2 characters representing the country.
Example: “CI” for Côte d'Ivoire, “BF” for Burkina Faso and “SN” for Senegal.

alpha3: string
ISO 3166 code with 3 characters representing the country.
Example: “CIV” for Côte d'Ivoire, “BFA” for Burkina Faso and “SEN” for Senegal.

name: string
Country name in either English or French, depending on the language of your FPay account. If, when you registered, you chose French as the language of your account, then the country name will be in French. in French and if you have chosen English, then this name will be in English.

key: string
Key uniquely identifying the money account provider.
The only possible values are"FPay" "MoovMoney" "MtnMoney" "OrangeMoney"

name: string
Money account provider name

amount

Amount

currency

AmountCurrency

code: string
The only possible value is"XOF"

unit: string
Symbol used to represent this currency. For now, the only value is "₣".

value: number
Numeric value of amount always positive or zero.

expire

Expire | undefined
If present, then this value indicates that this object has an expiry date and will be cancelled when it expires.

delay

Duration
Duration after which this object expires.

iso8601: string
Duration in ISO 8601 format

milliseconds: Double
Duration in milli seconds

seconds: Double
Duration in seconds

time

UTCDateTime

iso8601: string
Date and time in ISO 8601 format

timestamp

Timestamp

milliseconds: number
Date and time in timestamp milli seconds

seconds: Double
Date and time in timestamp seconds

fees

Fees

amount

Amount

currency

AmountCurrency

code: string
The only possible value is"XOF"

unit: string
Symbol used to represent this currency. For now, the only value is "₣".

value: number
Numeric value of amount always positive or zero.

payer: string | undefined
Who pays the fees associated with this operation ? If no costs are involved, this value will be omitted.
The only possible values are"Receiver" "Sender"

value

FeesValue

fixe: number
Fixed part of the fee amount. If the formula for calculating the fee is 1.5% + ₣150, then this field will have the value 150

percent: number
Variable part of the fee amount between 0 and 100. If the formula for calculating the fee is 1,5% + ₣150, then this field will have a value of 1,5.

foreignData: string | undefined
Your own data that you can attach to the object you've created. This can be JSON XML other data formats or simply Strings.
The maximum allowed length is 128 characters.

foreignId: string | undefined
ID Personalisé ou bien ID de votre système interne que vous souhaitez attacher à cet objet pour vous permettre de le récupérer plus tard.
Once created, this value cannot be modified.
This value must be unique for each type.
The maximum allowed length is 128 characters.

h1Descriptor

H1Descriptor | undefined

en: string | undefined

fr: string | undefined

id: string
Unique, unchangeable identifier made up of numbers and letters.

onFailure

OnFundRequestCompleted | undefined
Defines the actions to be taken by the FPAy server if this operation fails

redirectUserTo: string | undefined
Url to which the user will be redirected at the end of the operation. We recommend that you use an https url. You cannot provide an ip address or any other value in place of the domain name.

onSuccess

OnFundRequestCompleted | undefined
Defines the actions to be taken by the FPAy server if this operation is successful

redirectUserTo: string | undefined
Url to which the user will be redirected at the end of the operation. We recommend that you use an https url. You cannot provide an ip address or any other value in place of the domain name.

securePay

SecurePay

link: string
URL pointing to an image containing a QRCode to be scanned in order to be redirected the secure payment page to perform this operation.

purpose

SecurePayPurpose

SecurePayPurpose.Purchase
Purchase

_type: string
The only possible value is"Purchase"

label: string
The only possible values are"Buy" "Donate" "Participate" "Pay" "Subscribe"

SecurePayPurpose.Receive
Receive

_type: string
The only possible value is"Receive"

SecurePayPurpose.Send
Send

_type: string
The only possible value is"Send"

qrCode

QrCode

src: string
URL pointing to an image containing a QRCode to be scanned in order to be redirected the secure payment page to send or receive money.

sending: string
The only possible values are"NotYetDone" "PartiallyDone" "TotallyDone"

source

Source | undefined

Source.Multiple
Multiple

_type: string
The only possible value is"Multiple"

Source.Single
Single

_type: string
The only possible value is"Single"

account

MoneyAccount

balanceType: string
Indicates the type of balance used.
"AvailableBalance" literally means “Available Balance”. So, if the value of this field is “AvailableBalance”, then the funds are on the "AvailableBalance" and can be used. In some cases, funds are “Locked” (either on the "LockedInBalance" or "LockedOutBalance" ) and cannot be used until they are made available on the "AvailableBalance".
The only possible values are"AvailableBalance" "LockedInBalance" "LockedOutBalance"

identifier

MoneyAccountIdentifier

_type: string
Indicates the type of account on which “MoneyAccount” money is held. If it's a bank account, this field will have the value "Iban".
If it's a mobile money account, this field will have the value "MobileMoney".
If it's an FPay wallet, the value can be either "Id" or "Man", the latter meaning "Money Account Number".
The only possible values are"Iban" "Id" "Man" "MobileNumber"

value: string
Indicates the type of account on which “MoneyAccount” money is held. If it's a bank account, this field will have the value "Iban".
If it's a mobile money account, this field will have the value "MobileMoney".
If it's an FPay account, the value can be either "Id" or "Man", the latter meaning "Money Account Number".

provider

MoneyAccountProvider

country

Country

iso3166

Iso3166Country

alpha2: string
ISO 3166 code with 2 characters representing the country.
Example: “CI” for Côte d'Ivoire, “BF” for Burkina Faso and “SN” for Senegal.

alpha3: string
ISO 3166 code with 3 characters representing the country.
Example: “CIV” for Côte d'Ivoire, “BFA” for Burkina Faso and “SEN” for Senegal.

name: string
Country name in either English or French, depending on the language of your FPay account. If, when you registered, you chose French as the language of your account, then the country name will be in French. in French and if you have chosen English, then this name will be in English.

key: string
Key uniquely identifying the money account provider.
The only possible values are"FPay" "MoovMoney" "MtnMoney" "OrangeMoney"

name: string
Money account provider name

amount

Amount

currency

AmountCurrency

code: string
The only possible value is"XOF"

unit: string
Symbol used to represent this currency. For now, the only value is "₣".

value: number
Numeric value of amount always positive or zero.

status

FundRequestStatus

FundRequestStatus.Failure
Failure

_type: string
The only possible value is"Failure"

cancelled

Cancelled | undefined

afterTimeout: boolean

reason

LocalizedText

en: string

fr: string

FundRequestStatus.Processing
Processing

_type: string
The only possible value is"Processing"

reason

LocalizedText

en: string

fr: string

FundRequestStatus.Started
Started

_type: string
The only possible value is"Started"

FundRequestStatus.Starting
Starting

_type: string
The only possible value is"Starting"

FundRequestStatus.Successful
Successful

_type: string
The only possible value is"Successful"

FundRequestStatus.WaitingToStart
WaitingToStart

_type: string
The only possible value is"WaitingToStart"

url: string
URL on which a properly authorized GET method will return the instance of the object on which this field is defined.