ewalletTransaction/create webhook notification

The UNIPaaS system will update your platform of each transaction via the ewalletTransaction/create webhook. Including incoming and outgoing transactions. In most cases, you will receive more than one webhook notification for each transaction, as separate notifications will be fired for fees and splitted payments.

ewalletTransaction/create webhook

Use the ewalletTransaction/create webhook to keep your platform updated about every transaction that goes into or out of your vendor's eWallets, including fees and statuses.

Webhook fields and examples

The following is an example for the EwalletTransaction/create, for an incoming transaction (a vendor on your platform has received a payment)

{
  "merchantId": "634801efbf65c800ef3e66df",
  "vendorId": "634803b8e81da8def11e4329",
  "id": "152309",
  "amount": 10,
  "currency": "GBP",
  "reference": "INV-0063",
  "fees": 0,
  "type": "Charge",
  "transactionId": "639ed03d1258510111196a9e",
  "authorizationId": "639ed03d1258517389196a98",
  "transactionType": "Sale",
  "transactionResult": "Approved",
  "paymentMethod": "card",
  "payoutId": null,
  "brand": "visa",
  "issuerCountry": "GB",
  "reconciled": "false",
  "eWalletId": "105228",
  "netAmount": 10,
  "pendingAmount": 10,
  "payableAmount": 0,
  "reservedAmount": 0,
  "payableBalance": 49.95,
  "reservedBalance": 0,
  "identificationReference": "2535",
  "feeDesription": null,
  "hint": "",
  "metadata": {
    "accountCode": "090",
    "clientId": "18F8E1942DD04BB3B5E5A9551AB161C1",
    "clientSecret": "NL6CtohuGBtbW5jS55UrnDqO5GwS2sANcLLddUE-eFHzL9Qz"
  },
  "createdAt": "2022-12-18T08:33:04.763Z"
}

📘

Multiple webhook notifications for each transaction

You will receive multiple ewalletTransaction/create webhook notifications for most transactions. Each webhook notifications will represent a different aspect of a transaction, such as fees, authorization, etc.

Filtering out notifications

Some webhook notifications should be used by your platform to update the invoice status and account ledger. The following table will help you listen only to the relevant notifications.

We recommend you filter out all ewalletTransaction/create webhook notifications, except the following:

DescriptiontransactionType valuetransactionResult valuereconciled valueAction
A payment was receivedSaleApprovedfalseUpdate the invoice with PAID status

Update the account ledger
Required
A payment was refundedRefundApprovedfalseUpdate the invoice with REFUNDED status

Update the account ledger
Required
A payout was made to a vendor's bank accountPayoutApprovedirrelevantUpdate the invoice PAID INTO BANK ACCOUNT status

Update the account ledger
Required
A payment was settled (funds are available)SaleApprovedtrueOptional

📘

Payment attribution

Every webhook notification will contain a vendorId field which is used to attribute a transaction to a specific user on your platform.

Some transactions are attributed to your platform, these transactions will have the same ID in both vendorId and 'merchantId` fields

Object fields

The following table describes the most important ewalletTransaction/create object fields:

FieldDescription
vendorIdThe unique id of the vendor this transaction is relevant for
merchantIdThe unique id of the merchant this transaction is relevant for
idThe unique id of the record
amountTransaction amount
currencyTransaction currency
reference- Invoice number or reference number for incoming payments
- null for outgoing payments
fees- The sum amount of fees deducted for this transaction
type- Transaction type (it's better to use transactionType field)
transactionId- Identifier of this specific transaction
authorizationId- identifier of the authorization (refunds and chargebacks will have the same authorizationId as the original transaction)
transactionType- Represents the type of the transaction (Use this field to filter notifications)
transactionResultApproved - Incoming transaction was successfully executed
Declined - An incoming transaction attempt was declined
Pending - An incoming transaction is still processing
Error - There was an error with the transaction
Created - An outgoing transaction was successfully executed.
Cancelled - An outgoing transaction was cancelled

- Some transactionResult values are relevant to specific transactionType values. These are shown in the table below.
paymentMethodIndicates the payment method that was used to take the payment.
payoutIdA unique ID of an outgoing payment transaction.
brandThe card/bank brand that was used to take the payment.
issuerCountryIssuer country of the credit card that used during the payment
reconciled- Indicates if an incoming transaction was reconciled
- Not relevant for outgoing transactions
eWalletId- The ID of the eWallet that the transaction webhook is relevant for
netAmount- The transaction amount after deductions
pendingAmount- The transaction amount that is still not reconciled
payableAmount- The transaction amount that is available for payout after reconciliation
reservedAmount- The transaction amount that is reserved for risk purposes
payableBalance- The ewallet balance that is available for payout
reservedBalance- The ewallet balance that is reserved for risk purposes
consumerEmail- Email of the consumer that made the payment
consumerName- Name of the consumer that made the payment
consumerReference- Reference of the consumer that made the payment
identificationReference- Identification reference for payment method that has been used for the payment
feeDesription- Explanation about fees that has been charged for the payment
hint- Some hint related to fees
metadata- Field for custom data that has been used during checkout creation (useful for passing some internal properties)
checkoutId- A unique ID of the checkout used for this payment
createdAt- Timestamp for ewallet transaction entity