Initiate a new payment

post

https://eclipse-java-sandbox.ukheshe.rocks/eclipse-conductor/rest/v1/tenants/{tenantId}/payments

Starts the process of making a payment. The return result and flow depend on the payment type. E.g. it could be a mult-step process with customer interaction or a simple fire and forget payment.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

tenantId

int64

required

Body Params

Data to initiate a payment by someone that is not a customer on Eclipse. The payment could be to a QRCode or another supported payment destination.

accountNumber

string

length between 8 and 80

Account number

additionalFields

array of objects

Additional fields captured by the customer be submitted for processing. These fields relate to additionalFields requested when the payment was initiated or in the VAS catalog

additionalFields

additionalMerchantData

object

amount

number

≥ 0

The amount for the payment. Optional depending on the payment type. Amounts are in major currency unit. Note that this is the total amount of the payment. If the payment has a tip portion then the amount should reflect this. E.g. QRCode is 100, tip decided by customer is 10, the amount should be set as 110

branchCode

string

length between 2 and 20

Branch code

callbackUrl

string

length between 10 and 2000

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

cardOnFileId

string

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

currency

string

length between 3 and 3

The currency of the payment amount - e.g. USD, ZAR, NGN, TSH. Must be provided if the amount is provided. Otherwise do not provide

customFraudChecks

boolean

By default this value is false. If User wants to enable fraud rule checks then need to pass true

description

string

length between 0 and 200

A description for the payment if being initiated from Eclipse

destinationWalletId

int64

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

encryptedPaymentCardData

object

If the payment mechanism uses a card and its not a card on file (i.e. cardOnFileId not provided) and PaymentCardData is not provided then this field provides the encrypted card data to use for the payment. supported type(GooglePay)

expires

date-time

When the payment must complete by. If not in final state before this time, Eclipse will timeout the payment

externalUniqueId

string

required

length between 6 and 100

Provide a GUID for the payment to prevent replays/duplicates

externalWalletId

string

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.

externalWalletType

string

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.

landingUrl

string

length between 10 and 2000

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 it will be replaced with the paymentId before the redirect.

location

string

length between 0 and 200

Optional. Any location information to add to the payment such as GPS coordinates or branch name etc

maxAmount

number

This field specifies the maximum amount to make the partial payment

minAmount

number

This field specifies the minimum amount to make the partial payment

note

string

length between 0 and 200

Optional. User defined extra note related to payment in any format free text or JSON formatted text.

paymentCardData

object

If the payment mechanism uses a card and its not a card on file (i.e. cardOnFileId not provided) then this field provides the card data to use for the payment

paymentData

string

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.) )For payment links and payments destined to an Eclipse wallet, it must be populated with the destination wallet Id)

paymentMechanism

string

enum

The mechanism with which to make the payment. Determines if paymentCardData, paymentSecurity data etc are required. If not passed then the requests data like walletId, paymentCardData, paymentSecurityData etc will be used to work out the inferred mechanism

Allowed:

paymentSecurityData

object

Security data related to the payment in order to prove that the payer has authorised the transaction or that the issuer authorises the transaction on behalf of the payer (and hence accepts liability for the payment). Not required if COMPLETION_URL is used as the payment mechanism as the security data will be generated by Eclipse in concert with the issuing bank via an iFrame with the card holder

paymentTerminalData

object

Data about the terminal acquiring the payment

phone

string

Users primary mobile phone number. Optional/Required depending on the payment type

reference

string

replyPolicy

string

enum

Optional: Indicates to Eclipse whether to reply to the caller after the payment has completed. WHEN_COMPLETE: Eclipse will reply once he payment has reached a final state WHEN_RECEIVED: Eclipse will reply to the caller as soon as the payment is received by Eclipse (not necessarily completed). This is the default. WHEN_GUARANTEED: Not Applicable (acts same as WHEN_RECEIVED)

Allowed:

storeCardOnFile

boolean

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

templateId

string

Optional. If provided then card ui will be rendered based on the provided templateId else fallback to default tenant template.

type

string

enum

required

The type of payment being done. Indicates how Eclipse should process/parse the payment data as the payment data field is a loosely typed and could be a QRCode, JSON or any other data that Eclipse can pay. The type indicates what is being paid, not the payment mechanism.

unattended

boolean

Optional. Indicates that the customer is not present for the payment and interactive authentication must not happen (e.g. 3DS)

walletId

int64

Optional. If the payment mechanism is to pay with an Eclipse wallet, then the Eclipse walletId can be provided in this field

Responses

400

Bad Request

200OK