Payments

Unique identifier for the payment.

Unique identifier for the corresponding organization.

Unique identifier for the corresponding payment acceptor such as a website or a payment link.

Status of the payment, one of open, pending, authorized, verify, paid, void, denied, canceled, failed, or expired. Find more information about each status.

Timestamp of when the payment was created, in ISO 8601 format.

The amount of the payment, containing a string encoded value and the currency.

The URL the customer is redirected to after completing or canceling the payment.

Links to the payment object in the api, the checkout page, and the dashboard. Each sub-object contains the href and the type of the link.

The URL the payment status is sent to after the payment reaches these states: authorized, verify, paid, void, denied, canceled, failed, or expired.

Timestamp of when the payment was paid, in ISO 8601 format.

Timestamp of when the payment was authorized, in ISO 8601 format.

Timestamp of when the payment expires, in ISO 8601 format.

Timestamp of when the payment expired, in ISO 8601 format.

Timestamp of when the payment was canceled either by the shopper at the payment page or the merchant via the TapTree API. Timestamp is in ISO 8601 format.

Indicates whether the payment is processed in 'test' or 'live' mode. The used authentication token determines this setting, so you cannot use a test token to create live payments, but a live token for testmode by setting mode to test. Live tokens default to live, i.e., processing in livemode.

An optional description of the payment. Useful for displaying to the customer.

The payment method used for the payment, one of the methods available at the payment acceptor such as card, paypal, sofort, applepay, or googlepay. Automatically set when the payment is either authorized or paid.

If payment_method is defined (i.e., not null), a detail object is attached to the payment object, containing the details of the payment method.

If the payment was completed by card you will find details about bin, last4, security, expiry_year, and expiry_month as strings in this object.

If the payment was completed by a wallet such as Apple Pay or Google Pay, you will find a key wallet with the value applepay or googlepay respectively. For the key brand you will find the card brand such as visa, master, or amex.

If the payment was completed with PayPal you will find the customers email in this object.

The total amount that has been captured for this payment. Only present when capture_method is manual and the captured amount is greater than zero. Contains a string encoded value and the currency.

The total amount that has been refunded for this payment. Only present when the refunded amount is greater than zero. Contains a string encoded value and the currency.

The sequence type of the payment, either one_off or recurring (not functional yet). Defaults to one_off.

The environmental impact of the payment, containing the string encoded value and unit. The unit is currently always g CO2, but might be subject to change in the future.

This property lists the payment methods available for a payment while it is in the open state. Each key within this object represents a specific payment method, such as card, paypal, sofort, applepay, googlepay, and others. Accompanying each payment method is an impact object detailing the environmental impact associated paying with that method. This impact object includes both the value of the impact (quantitative measure) and its unit, which is currently denoted in g CO2. It's important to note that the impact unit may be updated in future versions.

You can iterate over the available_payment_methods object to retrieve the environmental impact for each payment method, or directly access the impact of a specific payment method using its key.

Details for billing, covering the address where billing documents are sent.

Information regarding the shipment of the product, including the recipient's address and contact details for accurate delivery.

Contains details about the customer involved in the transaction. It's essential for personalizing the transaction experience and for certain security protocols.

The amount you want to charge your customer, containing a string encoded value and the currency.

{ "value": "15.20", "currency": "eur" }

When you set up a payment, include a concise description that shows up on your customer's card or bank statement. This description helps both you and your customer quickly identify the transaction. To streamline record-keeping, incorporate a unique identifier into this description, linking it directly to a specific order in your system.

Be mindful of length; each payment method has a character limit for descriptions, with a maximum of 255 characters. If your description exceeds this limit, our system will automatically truncate it to comply. This truncation ensures compatibility across different payment platforms while maintaining essential details for easy reference.

After finishing the payment process, your customer will return to a specific URL you provide. It's useful to embed a unique identifier in the return_url, like the order ID. This way, you can present a page that's tailored to the particular order when your customer comes back.

Choose a webhook URL to receive updates on payment status. Although setting webhook_url is optional, not doing so means you'll miss critical notifications about changes in payment status.

Remember, the webhook URL must be externally accessible; localhost won't suffice. For local development, use a service like ngrok to route webhook calls to your local environment, ensuring you can test and handle payment updates effectively.

Set the locale property to define the language for the hosted payment pages your customers will see. Specifying a locale is strongly recommended as it can significantly boost your conversion rate. If you don't set a locale, the system defaults to the browser's language, provided it's compatible with the payment method. Use a locale in the ISO 15897 format, typically represented as xx_XX, where xx denotes the language code and XX the country code.

Supported locales include: de_DE, nl_NL, fr_FR, es_ES, en_US.

To enhance your checkout process, adjust the payment_methods parameter. This modification allows two primary functions: directly redirecting customers to a specific payment method or presenting a customized selection of payment options in our hosted checkout.

For direct redirection, specify a single method in payment_methods in the array, like ["paypal"]. This skips the standard choice screen and takes the customer straight to PayPal. This direct approach streamlines the payment experience, particularly useful when a preferred method is already known.

When multiple methods are preferred, list them in an array of strings within payment_methods. For instance, ["card", "applepay", "googlepay"] will display only these three options on the payment method screen. This method is especially beneficial for tailoring payment options to specific customer groups or regional preferences.

Available methods are: card paypal sofort applepay googlepay giropay eps alipay wechat ideal payconiq paysafecard przelewy riverty sepa_direct_debit trustly spraypay in3 blik

The capture_method parameter determines when the payment amount is captured. By default, the system automatically captures the payment amount when the payment is authorized. However, you can change this behavior by setting capture_method to manual. This setting allows you to capture the payment amount at a later time, typically up to five days after authorization. This approach is useful when you need to confirm the availability of goods or services before capturing the payment amount.

Note that the capture_method parameter only applies to eligible payment methods, such as card or paypal. For other payment methods, the system automatically captures the payment amount when the payment is authorized.

Available values: automatic and manual.

When true, creates a test payment even when using a live token.

Use the metadata property to add custom key-value pairs to an object, providing a structured way to store extra details. This feature is useful for including information specific to your needs, like tracking codes or customer notes.

Details for billing, covering the address where billing documents are sent.

Information regarding the shipment of the product, including the recipient's address and contact details for accurate delivery.

Contains details about the customer involved in the transaction. It's essential for personalizing the transaction experience and for certain security protocols.

Modify the description of the payment. Useful for adding or updating information visible to the customer. Note that the maximum length varies by payment method, up to 255 characters. Longer descriptions will be automatically truncated to fit the limits.

Update the URL to which your customer will be redirected after completing the payment. This is only editable if the payment is still open.

Change the webhook URL to receive payment status updates. The new URL will be used for sending notifications about subsequent payment state changes.

Add or update metadata associated with the payment. This can be any JSON object. Up to 20 key-value pairs can be added, with each key limited to 40 characters and each value to 500 characters. The total size cannot exceed 5,000 characters. The metadata is included whenever you fetch the payment details.

Adjust the language for the hosted payment pages. Accepts xx_XX format ISO 15897 locales. Useful for tailoring the customer's payment experience to their preferred language.

Set the maximum number of payments to return in one response. The limit can be up to 100 payments.

A payment id that acts as a cursor for pagination returning payments listed after this id. This parameter is useful when paginating through a large number of payments, where the response is split into multiple pages.

A payment id as a cursor for pagination. Returns payments listed before this id. Ideal for navigating to previous pages.