v1
latestOpenAPI 3.1.02026-07-24416405768.8 KBInitiate making a payment by a customer
The first step for a customer to make a payment
Path parameters
Request body
Account number
The amount for the payment. Optional depending on the payment type. Amounts are in major currency unit
Branch code
The URL Eclipse must post the PaymentResult to. Optional as one can always do a GET to get the result instead of using callbacks. This will be a system-system call
Optional. Card on file id for pre-enrolled cards to use for the payment if applicable. Negates the need to provide actual card data E.g. PAN etc
The currency of the payment amount - e.g. USD, ZAR, NGN, TSH. Must be provided if the amount is provided. Otherwise do not provide
By default this value is false. If User wants to enable fraud rule checks then need to pass true
A description for the payment if being initiated from Eclipse
Used to indicate where the funds must be paid to for payment types GLOBAL_PAYMENT_LINK, GLOBAL_REUSABLE_PAYMENT_LINK, GLOBAL_TOG, GLOBAL_TOG_VAC, GLOBAL_WALLET, KE_DTB_AIRTEL_PROMPT, KE_DTB_MPESA_PROMPT, KE_DTB_STK_PUSH, ZA_HALO, ZA_OZOW, ZA_PNP_CASH
When the payment must complete by. If not in final state before this time, Eclipse will timeout the payment
Provide a GUID for the payment to prevent replays/duplicates
Optional. If the payment mechanism is via some proprietary (non-card based) interface such as an external wallet or bank account then this field can be used to identity the payers wallet id, account number, profile id etc.
Optional. If the payment mechanism is via some proprietary (non-card based) interface such as an external wallet or bank account then this field can be used to identify what wallet type this is.
Where the customers iFrame/Browser should be navigated to after the payment has completed (applicable to payments that use 3DS). If the URL contains <paymentId> then <paymentId> will be replaced with the paymentId before the redirect.
Optional. Any location information to add to the payment such as GPS coordinates or branch name etc
This field specifies the maximum amount to make the partial payment
This field specifies the minimum amount to make the partial payment
Optional. User defined extra note related to payment in any format free text or JSON formatted text.
Loosely typed data about the payment. Depends on the payment type. E.g. could be a QRCode or a VAS partnerId, productId combination (For VAS the paymentData must consist of the partnerId and productId of a product in the VAS catalog separated with an _ e.g. 2_ABC123)
Payment mechanism. CARD: Credit/Debit/Prepaid card will be used with eitherthe card data provided, card on file ID, or by a lightbox the customer can capture the card details in, CARD_PRESENT: specifica use case of card present acquiring, typically used with pos estate or tap on glass integrations, WALLET: The debit should be done on an Eclipse walletId provided, EXTERNAL_WALLET: Pay with the externalWalletId and externalWalletIdType
Optional. If the payment mechanism is to pay with a card and card details are provided then this indicates whether to store the card on file
Optional. If provided then card ui will be rendered based on the provided templateId else fallback to default tenant template.
The type of payment being done
Optional. Indicates that the customer is not present for the payment and interactive authentication must not happen (e.g. 3DS)
Optional. If the payment mechanism is via an Eclipse wallet, then the Eclipse walletId can be provided in this field
Example request
{
"expires": "2022-03-10T12:15:50-04:00",
"paymentCardData": {
"deleteAt": "2022-03-10T12:15:50-04:00"
}
}Response
OK
If the payment can be made by card then the allowed card schemes that can be used
The ways that the payment can be made
The amount payable. Amounts are in major currency unit
Contain Json string for purchase amount minimum and maximum. If it is not empty then the purchase amount must be in between of min and max amount specified in this attribute(min and max inclusive) and that amount must be sent on the updated purchase request
Deprecated. Use phone instead
URL to open in an iFrame or browser where customer can securely complete 3DS details if required. Normally this will not be provided until the payment has been posted/updated with sufficient data to be processable. However this is provided for GLOBAL_PAYMENT_LINK payments as these dont require further info from the API caller for the payment to be made
When the payment was posted
The currency of the payment amount - e.g. USD, ZAR, NGN, TSH
A description for the payment created from the payment data.E.g. Merchant info and QR description for a QR payment
Data delivered to the chip card including the ARPC cryptogram for online issuer authentication
This will only be populated if there was an error
When the payment must complete by. If not in final state before this time, Eclipse will timeout the payment
Loosely typed data resulting from the payment. E.g. could be a voucher id if the payment was for a VAS. The structure depends on what was being paid for.
The transaction identifier for this payment as provided by the gateway itself
When the payment was last modified
Optional. Any location information to add to the payment such as GPS coordinates or branch name etc
The unique identifier for the merchant
The name of the merchant to whome the payment will go
Reference for the merchant
payment receiver’s wallet ID, if applicable.
Will be true if the value allows a partial payment and amount must be sent on the updated purchase request
Loosely typed data about the payment. Depends on the payment type. E.g. could be a QRCode
Unique identifier for this payment transaction
The deduced type of payment being done based on the type and paymentData
Status of a payment BUILDING: Not yet submitted as more data needs to be captured, PENDING:Being processed and can no longer be enhanced, SUCCESSFUL: Successfully completed, ERROR_PERM: Failed and wont ever succeed, ERROR_TEMP: Currently having an error but its being retried and may succeed or permanently fail, TIMEOUT: Failed as the process was not finalised in time, CANCELLED: Cancelled prior to SUCCESS or FAILURE, REVERSED: Reversed after success
Tracing data about the payment
Example response
{
"created": "2022-03-10T12:15:50-04:00",
"expires": "2022-03-10T12:15:50-04:00",
"lastModified": "2022-03-10T12:15:50-04:00"
}