Payment
The Payment object
Unique identifier for the object.
Has the value "live" if the object exists in live mode, or "sand" if it exists in test mode.
Possible values: [sand, live]
A unique string to reference the Payment. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the Payment with your internal systems.
Mode of this Payment.
Possible values: [Payment, Wallet, Setup]
The ID of the parent Payment, if this Payment is a child payment (e.g., a wallet).
The ID of the Company this Payment is associated with.
The ID of the Customer of this Payment.
The email address of the customer associated with this Payment. Required when customerId is not provided.
The first name of the customer associated with this Payment.
The last name of the customer associated with this Payment.
The phone number of the customer associated with this Payment.
The ID of the Customer's PaymentMethod to attach to this Payment.
Default PaymentGateway used for the first transaction.
The URL where the customer should be redirected to complete the payment. This URL is provided after creating a Payment and should be used to redirect the customer to the Voucherly checkout page.
closeCheckout object
Information about when and whether the checkout was closed by the customer.
Indicates whether the checkout was closed successfully (true) or cancelled (false).
The UTC timestamp when the checkout was closed.
callback object
Information about the last callback sent to your callbackUrl endpoint.
Indicates whether the callback was sent successfully (true) or failed (false).
The UTC timestamp when the last callback was sent.
The total amount of the payment before discounts, in cents. This is the sum of all line items.
The total amount of discounts applied to the payment, in cents. This is the sum of all discount amounts.
The final amount to be paid after applying all discounts, in cents. This is calculated as totalAmount - discountAmount.
The total amount that has been paid so far, in cents. This includes both regular payments and voucher payments.
The amount that has been paid using vouchers, in cents.
The remaining amount to be paid, in cents. This is calculated as finalAmount - paidAmount.
Current status of the Payment.
Possible values: [Requested, Paid, Confirmed, Refunded, Cancelled, Voided, Expired]
metadata objectnullable
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. It can contain up to 10 key-value items with a maximum length of 40 for the key and of 400 chars for the value.
transactions object[]
An array of Transaction objects representing all payment attempts and transactions associated with this Payment.
Unique identifier for the transaction.
The ID of the PaymentGateway used for this transaction.
paymentGateway object
Essential information about the PaymentGateway used for this transaction.
Unique identifier for the PaymentGateway.
The display name of the PaymentGateway (e.g., "Visa", "Mastercard", "Edenred").
The type of payment gateway.
Possible values: [0, 1, 2]
The type of checkout action required by the payment gateway.
Possible values: [OTP, REDIRECT, DROPIN]
URL of the image to display for this PaymentGateway.
URL of the icon to display for this PaymentGateway.
The primary external transaction ID from the payment gateway provider.
An additional external transaction ID or reference from the payment gateway provider.
A third external transaction ID or reference from the payment gateway provider.
Indicates whether this transaction was paid using the customer's wallet balance.
error object
Error information if the transaction failed.
The type of error returned.
Possible values: [Generic, Cancelled, NotCompleted, MissingPaymentMethod, Declined, System]
externalError object
Error information returned by an external payment gateway provider.
A human-readable error message from the payment gateway.
An error code from the payment gateway provider.
The amount that was requested for this transaction, in cents.
The actual amount processed in this transaction, in cents.
The amount paid using vouchers in this transaction, in cents.
The number of vouchers used in this transaction.
The amount that has been confirmed (captured) from this transaction, in cents.
The amount that has been refunded from this transaction, in cents.
The currency code for this transaction (e.g., "EUR", "USD").
creditCard object
If this is a card PaymentMethod, this contains the user’s card details.
Card brand
Card masked PAN
The card's expiration date, typically in MM/YY format.
Two-digit number representing the card’s expiration month.
Four-digit number representing the card’s expiration year.
The card product type (e.g., "Visa Classic", "Mastercard Gold").
directDebit object
If this is a sepa_debit PaymentMethod, this contains the user’s card details.
ID of the bank account.
BIC of the bank account.
IBAN of the bank account.
The email address of the payment method holder for this transaction.
The name of the payment method holder for this transaction.
The current status of this transaction.
Possible values: [Requested, Paid, Confirmed, Refunded, RefundedPartially, Cancelled, Failed, Voided, Expired, Reversed, ImpossibleRefund, NextAction]
request object
Information about the payment request, including any redirect URL or action required.
The type of checkout action required by the payment gateway.
Possible values: [OTP, REDIRECT, DROPIN]
The unique identifier of the transaction in the external payment gateway system.
The URL to redirect the customer to, if the action is REDIRECT. This URL is provided by the payment gateway.
Information about the payment request, including any redirect URL or action required.
discounts object[]
An array of PaymentDiscount objects representing all discounts applied to this Payment.
The discount’s name, meant to be displayable to the customer.
The discount’s description. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes.
A non-negative integer in cents representing how much to subtract from the total. Must be specified when both type and value are null.
Defines how the discount is calculated:
DOLLAROFF: A fixed amount in cents is subtracted from the total.PERCENOFF: A percentage of the total amount is subtracted.FIXED: The final price is set to a fixed amount, overriding the original total.
Possible values: [DOLLAROFF, PERCENOFF, FIXED]
The value of the discount, contextual to the selected type. Must be specified when type is provided and amount is null.
Defines the application order of this discount relative to others.
lines object[]
An array of PaymentLine objects representing the line items (products or services) included in this Payment.
The quantity of the line item being purchased.
A non-negative integer in cents representing how much to charge for each individual unit.
A non-negative integer in cents representing the discount applied to each individual unit.
A non-negative integer in cents representing the total discount applied to the entire line.
A non-negative integer in cents representing the final amount charged for this line, after discounts.
The ID of the Product that this PaymentLine refers to, when the line was created against an existing Voucherly Product.
The product’s name, meant to be displayable to the customer.
The product’s variant description, meant to be displayable to the customer.
The product’s image URL, meant to be displayable to the customer.
Primary external reference for the product, used by Voucherly to reconcile the product across systems and to correctly compute reporting.
Secondary external reference for the product, used by Voucherly to reconcile the product across systems and to correctly compute reporting.
The product's applicable tax rate.
Indicates whether this PaymentLine refers to a food item. This flag is used to determine eligibility for meal vouchers or similar benefits.
Indicates whether this PaymentLine is a gift item.
{
"id": "string",
"tenant": "sand",
"referenceId": "string",
"mode": "Payment",
"parentPaymentId": "string",
"companyId": "string",
"customerId": "string",
"customerEmail": "string",
"customerFirstName": "string",
"customerLastName": "string",
"customerPhoneNumber": "string",
"customerPaymentMethodId": "string",
"selectedPaymentGatewayId": "string",
"checkoutUrl": "string",
"closeCheckout": {
"success": true,
"date": "2024-07-29T15:51:28.071Z"
},
"callback": {
"success": true,
"date": "2024-07-29T15:51:28.071Z"
},
"totalAmount": 0,
"discountAmount": 0,
"finalAmount": 0,
"paidAmount": 0,
"paidVoucherAmount": 0,
"amount": 0,
"status": "Requested",
"metadata": {},
"transactions": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"paymentGatewayId": "string",
"paymentGateway": {
"id": "string",
"name": "string",
"type": 0,
"paymentAction": "OTP",
"image": "string",
"icon": "string"
},
"externalId1": "string",
"externalId2": "string",
"externalId3": "string",
"isWallet": true,
"error": {
"code": "Generic",
"externalError": {
"message": "string",
"code": "string"
}
},
"requestedAmount": 0,
"amount": 0,
"voucherAmount": 0,
"noOfVouchers": 0,
"confirmedAmount": 0,
"refundedAmount": 0,
"currency": "string",
"creditCard": {
"brand": "string",
"pan": "string",
"expiration": "string",
"expirationMonth": 0,
"expirationYear": 0,
"product": "string"
},
"directDebit": {
"accountId": "string",
"accountBic": "string",
"accountIban": "string"
},
"holderEmail": "string",
"holderName": "string",
"status": "Requested",
"request": {
"action": "OTP",
"externalTransactionId": "string",
"url": "string"
}
}
],
"discounts": [
{
"discountName": "string",
"discountDescription": "string",
"amount": 0,
"type": "DOLLAROFF",
"value": 0,
"index": 0
}
],
"lines": [
{
"quantity": 0,
"unitAmount": 0,
"unitDiscountAmount": 0,
"discountAmount": 0,
"finalAmount": 0,
"productId": "string",
"productName": "string",
"productVariant": "string",
"productImage": "string",
"productExternalId1": "string",
"productExternalId2": "string",
"taxRate": 0,
"isFood": true,
"isGift": true
}
]
}