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.
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
Detailed information about the PaymentGateway used for this transaction.
Unique identifier for the payment gateway.
The display name of the payment gateway (e.g., "Visa", "Mastercard", "Edenred").
The type of payment gateway (0 = Card, 1 = Voucher, 2 = Other).
Possible values: [0, 1, 2]
The type of checkout action required by this payment gateway.
Possible values: [OTP, REDIRECT, DROPIN]
URL of the image to display for this payment gateway in the checkout.
URL of the image to display for this payment gateway in the checkout page.
URL of the icon to display for this payment gateway.
The minimum payment amount required for this payment gateway, in cents.
Indicates whether partial refunds are supported by this payment gateway.
Indicates whether payment methods can be saved (tokenized) for future use with this payment gateway.
paymentGatewayParameters object[]nullable
An array of configuration parameters for this payment gateway.
The ID of the payment gateway this parameter belongs to.
The unique identifier of this parameter.
A human-readable name for this parameter.
Indicates whether this parameter is configured at the merchant level.
Indicates whether this parameter should be displayed as a form field.
Indicates whether this parameter should be visible in the UI.
Indicates whether this parameter is required.
The default value for this parameter at the tenant level.
options object[]nullable
An array of available options for this parameter, if it's a select/dropdown type.
The unique identifier of this option.
The display text for this option.
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 to complete the payment.
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.
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.
The ID of the Product that this PaymentLine will belong to. One of productId or productName is required. When productId is provided, all other product-related fields will be ignored, as their values will be automatically loaded from the Product.
The product’s name, meant to be displayable to the customer. One of productId or productName is required.
The product’s variant description, meant to be displayable to the customer.
The product’s image, meant to be displayable to the customer.
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. This field is mutually exclusive with discountAmount — only one of the two may be specified.
A non-negative integer in cents representing the total discount applied to the entire line. This field is mutually exclusive with unitDiscountAmount — only one of the two may be specified.
A non-negative integer in cents representing how much to charge.
The product's applicable tax rate.
Indicates whether this payment line refers to a food item. This flag is used to determine eligibility for meal vouchers or similar benefits.
modifiers object[]nullable
The ID of the Modifier that this customization will belong to.
The ID of the Product that this customization will belong to.
The name of the modifier product, automatically loaded from the Product.
The quantity of this modifier.
The price of this modifier, in cents.
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.
The Payment object
{
"id": "string",
"tenant": "sand",
"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",
"checkoutImage": "string",
"icon": "string",
"minimumAmount": 0,
"isRefundablePartially": true,
"isTokenizable": true,
"paymentGatewayParameters": [
{
"paymentGatewayId": "string",
"parameterId": "string",
"friendlyName": "string",
"isMerchant": true,
"isForm": true,
"isVisible": true,
"isRequired": true,
"tenantDefaultValue": "string",
"options": [
{
"id": "string",
"text": "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"
}
}
],
"lines": [
{
"quantity": 0,
"productId": "string",
"productName": "string",
"productVariant": "string",
"productImage": "string",
"unitAmount": 0,
"unitDiscountAmount": 0,
"discountAmount": 0,
"finalAmount": 0,
"taxRate": 0,
"isFood": true,
"modifiers": [
{
"modifierId": "string",
"productId": "string",
"productName": "string",
"quantity": 0,
"price": 0
}
]
}
],
"discounts": [
{
"discountName": "string",
"discountDescription": "string",
"amount": 0,
"type": "DOLLAROFF",
"value": 0,
"index": 0
}
]
}