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]
The ID of the merchant this Payment belongs to, that is your own merchant.
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.
The identifier of the order this Payment settles in your own 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 Store this Payment belongs to.
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 PaymentGateway preselected for the first transaction.
The IDs of the PaymentGateways the payer is allowed to choose from, when the choice was restricted.
The ID of the PaymentGatewayAccount used to process this Payment.
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.
The URL Voucherly calls server to server when the Payment changes status.
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 with a digital payment method, in cents.
The amount that has been paid using vouchers, in cents.
The amount that has been paid with a fringe benefit credit, in cents.
The amount that has been paid in cash, 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]
The amount that has been confirmed (captured), in cents.
The date and time the Payment was confirmed, in UTC.
The amount that has been cancelled, in cents.
The amount that has been refunded, in cents.
The date and time the Payment was refunded, in UTC.
The ID of the Receipt issued for this Payment.
The ID of the Receipt issued for the refund of this Payment.
receipt object
The Receipt issued for this Payment.
Unique identifier for the Receipt.
The identifier assigned to the Receipt by the upstream fiscal provider.
The fiscal Receipt number.
The UTC timestamp when the Receipt was issued.
The fiscal type of the Receipt:
Sale: receipt issued for a successful Payment.Void: receipt issued for a void or refund operation.
Possible values: [Sale, Void]
The total amount of the Receipt, in cents.
The ID of the parent Receipt, when this Receipt is a void/refund of a previously issued Sale Receipt.
refundReceipt object
The Receipt issued for the refund of this Payment.
Unique identifier for the Receipt.
The identifier assigned to the Receipt by the upstream fiscal provider.
The fiscal Receipt number.
The UTC timestamp when the Receipt was issued.
The fiscal type of the Receipt:
Sale: receipt issued for a successful Payment.Void: receipt issued for a void or refund operation.
Possible values: [Sale, Void]
The total amount of the Receipt, in cents.
The ID of the parent Receipt, when this Receipt is a void/refund of a previously issued Sale Receipt.
The date and time the Payment was created, in UTC.
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 PaymentGatewayAccount that processed this 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").
URL of the image to display for this PaymentGateway.
Null when the PaymentGateway is no longer offered and only survives on historical records.
Possible values: [0, 1, 2]
Null when the PaymentGateway is no longer offered and only survives on historical records.
Possible values: [OTP, REDIRECT, DROPIN]
The ID of the secondary PaymentGateway, when the transaction rides on another gateway (e.g. a wallet on a card gateway).
The ID of the Terminal that took the payment, for card-present transactions.
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.
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 date and time the transaction was requested, in UTC.
The amount that was requested for this transaction, in cents.
The part of the requested amount the gateway could not charge because it sits below its minimum, in cents.
The actual amount processed in this transaction, in cents.
The amount paid with a digital payment method in this transaction, in cents.
The amount paid using vouchers in this transaction, in cents.
The amount paid with a fringe benefit credit in this transaction, in cents.
The amount paid in cash 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 date and time the transaction was paid, in UTC.
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.
nextAction object
The action the payer still has to perform for the transaction to complete.
params object
The gateway specific parameters describing the action.
The gateway specific parameters describing the action.
operations object[]nullable
The confirm, refund, cancel and reverse operations performed on this transaction.
The identifier of the operation.
The kind of operation performed on a Transaction.
Possible values: [Confirm, Refund, Cancel, Reverse]
The amount the operation moved, in cents.
The date and time the operation was performed, in UTC.
Whether the operation succeeded.
The identifier of the operation in the PaymentGateway provider system.
error object
The error returned when the operation failed.
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.
Whether the failure comes from Voucherly rather than from the PaymentGateway provider.
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.
Primary external reference for the discount, used by Voucherly to reconcile it across systems and to correctly compute reporting.
Secondary external reference for the discount, used by Voucherly to reconcile it across systems and to correctly compute reporting.
The coupon code the payer entered to obtain this discount.
The loyalty points spent to obtain this discount.
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.
Where the PaymentLine comes from:
Standard: the line was part of the original order.TableUpsell: the line was added by an upselling proposal accepted while paying at the table.
Possible values: [Standard, TableUpsell]
{
"id": "string",
"tenant": "sand",
"merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"referenceId": "string",
"externalOrderId": "string",
"mode": "Payment",
"parentPaymentId": "string",
"companyId": "string",
"storeId": "string",
"customerId": "string",
"customerEmail": "string",
"customerFirstName": "string",
"customerLastName": "string",
"customerPhoneNumber": "string",
"selectedPaymentGateway": "string",
"paymentGateways": [
"string"
],
"paymentGatewayConfigurationId": "string",
"checkoutUrl": "string",
"callbackUrl": "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,
"paidDigitalAmount": 0,
"paidVoucherAmount": 0,
"paidFringeAmount": 0,
"paidCashAmount": 0,
"amount": 0,
"status": "Requested",
"confirmedAmount": 0,
"confirmedOnUtc": "2024-07-29T15:51:28.071Z",
"cancelledAmount": 0,
"refundedAmount": 0,
"refundedOnUtc": "2024-07-29T15:51:28.071Z",
"receiptId": "string",
"refundReceiptId": "string",
"receipt": {
"id": "string",
"externalId": "string",
"number": "string",
"date": "2024-07-29T15:51:28.071Z",
"type": "Sale",
"amount": 0,
"parentReceiptId": "string"
},
"refundReceipt": {
"id": "string",
"externalId": "string",
"number": "string",
"date": "2024-07-29T15:51:28.071Z",
"type": "Sale",
"amount": 0,
"parentReceiptId": "string"
},
"created": "2024-07-29T15:51:28.071Z",
"metadata": {},
"transactions": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"paymentGatewayAccountId": "string",
"paymentGatewayId": "string",
"paymentGateway": {
"id": "string",
"name": "string",
"image": "string",
"type": 0,
"paymentAction": "OTP"
},
"paymentGatewayId2": "string",
"terminalId": "string",
"externalId1": "string",
"externalId2": "string",
"externalId3": "string",
"error": {
"code": "Generic",
"externalError": {
"message": "string",
"code": "string"
}
},
"requestedAt": "2024-07-29T15:51:28.071Z",
"requestedAmount": 0,
"exceedingAmount": 0,
"amount": 0,
"digitalAmount": 0,
"voucherAmount": 0,
"fringeAmount": 0,
"cashAmount": 0,
"noOfVouchers": 0,
"confirmedAmount": 0,
"refundedAmount": 0,
"paidOnUtc": "2024-07-29T15:51:28.071Z",
"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"
},
"nextAction": {
"params": {}
},
"operations": [
{
"id": 0,
"operation": "Confirm",
"amount": 0,
"occurredOnUtc": "2024-07-29T15:51:28.071Z",
"success": true,
"externalId": "string",
"error": {
"externalError": {
"message": "string",
"code": "string"
},
"isSystemError": true
}
}
]
}
],
"discounts": [
{
"discountName": "string",
"discountDescription": "string",
"amount": 0,
"type": "DOLLAROFF",
"value": 0,
"index": 0,
"externalId1": "string",
"externalId2": "string",
"couponCode": "string",
"points": 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,
"origin": "Standard"
}
]
}