# List stores Source: https://docs.dintero.com/api-reference/account-stores/aid_account_management_stores_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/stores Get details about the account stores scopes: - admin:accounts - read:accounts # Create store Source: https://docs.dintero.com/api-reference/account-stores/aid_account_management_stores_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/stores Create a store scopes: - admin:accounts - write:accounts # Delete store Source: https://docs.dintero.com/api-reference/account-stores/aid_account_management_stores_sid_delete /mintlify-docs/openapi/spec-payments-v2.yaml delete /accounts/{aid}/stores/{store_id} Delete single store. The store's BankAxept (BAX) merchant agreements are deleted too, so their `bax_number` can be used again. A store that has terminals cannot be deleted. The request fails with `409` and the error code `STORE_HAS_TERMINALS`. Delete the terminals first. scopes: - admin:accounts - write:accounts # Store details Source: https://docs.dintero.com/api-reference/account-stores/aid_account_management_stores_sid_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/stores/{store_id} Get store details scopes: - admin:accounts - read:accounts # Update store Source: https://docs.dintero.com/api-reference/account-stores/aid_account_management_stores_sid_put /mintlify-docs/openapi/spec-payments-v2.yaml put /accounts/{aid}/stores/{store_id} Update store properties scopes: - admin:accounts - write:accounts # List terminals Source: https://docs.dintero.com/api-reference/account-terminals/aid_account_management_terminals_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/terminals List terminals for the account. Filter by store, payout destination, status, device model, or serial number. scopes: - admin:accounts - read:accounts # Create terminal Source: https://docs.dintero.com/api-reference/account-terminals/aid_account_management_terminals_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/terminals Register a physical payment terminal and associate it with a store. Fails with `400` `STORE_NOT_ACTIVE` if the store is not `ACTIVE`. scopes: - admin:accounts - write:accounts # Delete terminal Source: https://docs.dintero.com/api-reference/account-terminals/aid_account_management_terminals_termid_delete /mintlify-docs/openapi/spec-payments-v2.yaml delete /accounts/{aid}/terminals/{terminal_id} Remove a terminal from the account. Removing a terminal also starts an `end_of_day` operation on it, to close the terminal's open batch. The operation runs asynchronously and does not block or fail the removal. Its result is available from `GET /v1/accounts/{aid}/payments/admin/terminals/operations?terminal_id={terminal_id}`. A terminal that is turned off or unreachable ends the operation as `TIMEOUT`. No operation is created for a terminal that is not active, for example one still being activated. scopes: - admin:accounts - write:accounts # Terminal details Source: https://docs.dintero.com/api-reference/account-terminals/aid_account_management_terminals_termid_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/terminals/{terminal_id} Get details for a single terminal. scopes: - admin:accounts - read:accounts # Search external postal place Source: https://docs.dintero.com/api-reference/addresses/aid_search_external_postal_place /mintlify-docs/openapi/spec-customers.yaml get /accounts/{aid}/search/external/postal_place/{country}/{postal_code} Get postal place by country and postal code. scopes: - public # Validate address Source: https://docs.dintero.com/api-reference/addresses/aid_search_external_validate_address /mintlify-docs/openapi/spec-customers.yaml post /accounts/{aid}/search/external/address/{country}/validate Validate the given address and return close matching alternative suggestions if the provided address was most likely wrong. scopes: - public # List payment approvals Source: https://docs.dintero.com/api-reference/approvals/aid_management_settings_approvals_payment_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/management/settings/approvals/payments scopes: - admin:accounts - read:accounts # New payment approval Source: https://docs.dintero.com/api-reference/approvals/aid_management_settings_approvals_payment_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/management/settings/approvals/payments Initiate an application for using Dintero payments . The application will contain a link to an URL where the signatory of the account will need to finish submission of the case contract and sign it. Dintero will perform a KYC, AML and bank ownership check before the application `case_status`will be updated to `ACTIVE`. Once the application is approved we will set up your account for using Dintero payments. Note that not all payment methods are available in all countries, and that for some payments methods some processing time must be expected before you can start accepting payments. scopes: - admin:accounts - write:accounts - write:accounts:/management/settings/approvals # List seller approvals Source: https://docs.dintero.com/api-reference/approvals/aid_management_settings_approvals_payout_destinations_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/management/settings/approvals/payout-destinations scopes: - admin:accounts - read:accounts # New seller approval Source: https://docs.dintero.com/api-reference/approvals/aid_management_settings_approvals_payout_destinations_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/management/settings/approvals/payout-destinations Initiate an application for a new seller for Dintero Payout with split-payment. The application will contain a link to an URL where the signatory of the seller will need to finish submission of the case contract and sign it. Dintero will perform a KYC, AML and bank ownership check on the seller before the application `case_status`will be updated to `ACTIVE`. Once the application is approved, the payout destination will be added automatically to the Dintero Payout service. scopes: - admin:accounts - write:accounts - write:accounts:/management/settings/approvals --- For testing purposes it is possible to auto-approve or decline a new seller by adding one of the following values to `payout_destination_description`: - "AUTO_APPROVE": Approves the case automatically, the case status will be set to `ACTIVE` - "AUTO_DECLINE": Declines the case automatically, the case status will be set to `DECLINED` - "AUTO_WAITING_FOR_SIGNATURE": Leaves the signature check for the case, the case status will be set to `WAITING_FOR_SIGNATURE` NOTE: This behavior is only available in test mode, i.e. with an `aid` prefixed with "T". --- Dintero admins (access tokens with the `admin:dintero` scope) can replace Dintero's standard terms for sellers with links to custom agreements by supplying `custom_agreements`. A case created with `custom_agreements` is always reviewed manually, it is never approved automatically. # Get Token Source: https://docs.dintero.com/api-reference/authenticate/aid_auths_oauth_token_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{oid}/auth/token Use this endpoint to directly request an access_token ### Client Access Token Use HTTP Basic authentication scheme for authenticating grant_type `client_credentials`, use client_id/client_secret as user/password. ### Code/Password Token Use HTTP Bearer authentication scheme for authenticating grant_type `authorization_code` or `password`, where the Bearer value must be a JWT toke with access to the token endpoint. ### Account User Token Use HTTP Bearer authentication scheme for authenticating grant_type `account_user_token`, where the Bearer value must be a account user JWT token. > Use ID token as Bearer toke if the user was authenticated > externally. The ID must include a `email` claim that > identifies the account user. ### Refresh Token Use HTTP Bearer authentication scheme for authenticating grant_type `refresh_token` where the Bearer value **must** be an Access Token for the clients that was used to create the Refresh Token. ### Multi-factor authentication (MFA) When a request is made to the endpoint to get an access token, normally you either get an error, or you get an access token. However, when the MFA is enabled, the endpoint may return a new error with `error.code: mfa_required`. When an `mfa_required` error is returned, the client must perform a `challenge`. This is done by sending a request to the [auth/mfa/challenge](/management-auth-api/challenge/aid_auth_mfa_challenge_post) endpoint To verify MFA using an OOB challenge, the client must make a request to this endpoint with `grant_type=mfa-oob`. Include the `oob_code` you received from the challenge response, as well as the `mfa_token` you received as part of mfa_required error. scopes: - admin:accounts - write:accounts - write:accounts:/auth/users - write:accounts:/auth/users/no-mfa # Delete campagn Source: https://docs.dintero.com/api-reference/campaigns/aid_discounts_campaigns_campaign_id_delete /mintlify-docs/openapi/spec-discounts.yaml delete /accounts/{aid}/discounts/campaigns/{campaign_id} Delete a campagn. Deleting a campagn does not affect its discount rules. i.e. active campagn rules will continue to be active after deleting the campagn scopes: - admin:discounts - write:discounts # Campaign details Source: https://docs.dintero.com/api-reference/campaigns/aid_discounts_campaigns_campaign_id_get /mintlify-docs/openapi/spec-discounts.yaml get /accounts/{aid}/discounts/campaigns/{campaign_id} Get more details about a campaign scopes: - admin:discounts - read:discounts # Update Campaign Source: https://docs.dintero.com/api-reference/campaigns/aid_discounts_campaigns_campaign_id_put /mintlify-docs/openapi/spec-discounts.yaml put /accounts/{aid}/discounts/campaigns/{campaign_id} Update campaign details. Undeletes a deleted campaign. scopes: - admin:discounts - write:discounts # Campaigns collection Source: https://docs.dintero.com/api-reference/campaigns/aid_discounts_campaigns_get /mintlify-docs/openapi/spec-discounts.yaml get /accounts/{aid}/discounts/campaigns List campaigns scopes: - admin:discounts - read:discounts # Create new campaign Source: https://docs.dintero.com/api-reference/campaigns/aid_discounts_campaigns_post /mintlify-docs/openapi/spec-discounts.yaml post /accounts/{aid}/discounts/campaigns Create a new campaign to group discount rules scopes: - admin:discounts - write:discounts # List card tokens Source: https://docs.dintero.com/api-reference/card-tokens/card_tokens_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/payments/card-tokens Use query parameters to filter the search. To list all Transactions related to a Card Token, use [GET /v1/transactions](/api-reference/transactions/transactions_get) with query `?search={token_id}`. scopes: - admin:checkout # Delete card token Source: https://docs.dintero.com/api-reference/card-tokens/card_tokens_token_id_delete /mintlify-docs/openapi/spec-payments-v2.yaml delete /accounts/{aid}/payments/card-tokens/{token_id} scopes: - admin:checkout # Get card token Source: https://docs.dintero.com/api-reference/card-tokens/card_tokens_token_id_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/payments/card-tokens/{token_id} scopes: - admin:checkout # Batch create cards Source: https://docs.dintero.com/api-reference/cards/aid_cards_batch_post /mintlify-docs/openapi/spec-wallets.yaml post /accounts/{aid}/wallets/cards/batch Batch create cards. The cards created from the batch operation will all have zero balance and status `inactive`. They all need to be activated before use. scopes: - admin:wallets - write:wallets # Activate card Source: https://docs.dintero.com/api-reference/cards/aid_cards_cardid_activate_post /mintlify-docs/openapi/spec-wallets.yaml post /accounts/{aid}/wallets/cards/{card_id}/activate Activate a card with status `inactive` scopes: - admin:wallets - write:wallets - write:wallets:/activate # Retrieve card by card ID Source: https://docs.dintero.com/api-reference/cards/aid_cards_cardid_get /mintlify-docs/openapi/spec-wallets.yaml get /accounts/{aid}/wallets/cards/{card_id} Get all details about a card scopes: - admin:wallets - read:wallets # Rotate Pin Source: https://docs.dintero.com/api-reference/cards/aid_cards_cardid_rotate_pin_post /mintlify-docs/openapi/spec-wallets.yaml post /accounts/{aid}/wallets/cards/{card_id}/rotate-pin Rotate or add new pin to card scopes: - admin:wallets - write:wallets # Create a token for the card Source: https://docs.dintero.com/api-reference/cards/aid_cards_cardid_token_post /mintlify-docs/openapi/spec-wallets.yaml post /accounts/{aid}/wallets/cards/{card_id}/tokens Create a temporary `token` (also referred as Card Code) for the card, an temporary alias that must be used when when creating a drawdown transaction The token can be stored in a barcode to allow use of virtuell card in purchase in POS or webstore scopes: - admin:wallets - write:wallets # Get cards Source: https://docs.dintero.com/api-reference/cards/aid_cards_get /mintlify-docs/openapi/spec-wallets.yaml get /accounts/{aid}/wallets/cards Get all cards for an account scopes: - admin:wallets - read:wallets # Create a card Source: https://docs.dintero.com/api-reference/cards/aid_cards_post /mintlify-docs/openapi/spec-wallets.yaml post /accounts/{aid}/wallets/cards Create a new card scopes: - admin:wallets - write:wallets # Retrieve card by Token Source: https://docs.dintero.com/api-reference/cards/aid_cards_token_post /mintlify-docs/openapi/spec-wallets.yaml post /accounts/{aid}/wallets/info Get details about a card, including the current balance and available funds. No details will be returned for expired tokens scopes: - admin:wallets - write:wallets - write:wallets:/info # Clients collection Source: https://docs.dintero.com/api-reference/clients/aid_auth_clients_get /mintlify-docs/openapi/spec-management-auth.yaml get /accounts/{oid}/auth/clients Retrieve a list of all client applications scopes: - admin:accounts - read:accounts # Create Client Source: https://docs.dintero.com/api-reference/clients/aid_auth_clients_post /mintlify-docs/openapi/spec-management-auth.yaml post /accounts/{oid}/auth/clients Creates a new client application. scopes: - admin:accounts - write:accounts # Delete Client Source: https://docs.dintero.com/api-reference/clients/aid_auths_clients_id_delete /mintlify-docs/openapi/spec-management-auth.yaml delete /accounts/{oid}/auth/clients/{id} Deletes a client and all its related assets scopes: - admin:accounts - write:accounts # Get Client Source: https://docs.dintero.com/api-reference/clients/aid_auths_clients_id_get /mintlify-docs/openapi/spec-management-auth.yaml get /accounts/{oid}/auth/clients/{id} Retrieves a client by its id. scopes: - admin:accounts - read:accounts # Update Client Source: https://docs.dintero.com/api-reference/clients/aid_auths_clients_id_patch /mintlify-docs/openapi/spec-management-auth.yaml patch /accounts/{oid}/auth/clients/{id} Update client details scopes: - admin:accounts - read:accounts # Rotate a client secret. Source: https://docs.dintero.com/api-reference/clients/aid_auths_clients_id_rotate_post /mintlify-docs/openapi/spec-management-auth.yaml post /accounts/{oid}/auth/clients/{id}/rotate-secret Rotate a client secret. scopes: - admin:accounts - write:accounts # Customer email/phone_number Status Source: https://docs.dintero.com/api-reference/communication/aid_customers_cid_verify_get /mintlify-docs/openapi/spec-customers.yaml get /accounts/{aid}/customers/users/{customer_id}/communication Get the status of customer email / phone_number communication scopes: - admin:customers - read:customers - user:customers # Verify Customer email/phone_number Source: https://docs.dintero.com/api-reference/communication/aid_customers_cid_verify_post /mintlify-docs/openapi/spec-customers.yaml post /accounts/{aid}/customers/users/{customer_id}/communication/{operation}/{field} Verify customer email/phone_number field. Consist of to steps: - send verification code to the customer (sms or email) - verify the email/phone_number by posting verification code sent to customer scopes: - admin:customers - write:customers - user:customers # Get departments Source: https://docs.dintero.com/api-reference/company/aid_company_departments_get /mintlify-docs/openapi/spec-customers.yaml get /accounts/{aid}/customers/company/departments List all departments register by company customers scopes: - admin:customers - read:customers - public:customers # Customer Receipts collection Source: https://docs.dintero.com/api-reference/customer-receipts/aid_receipts_customers_cid_get /mintlify-docs/openapi/spec-receipts.yaml get /accounts/{aid}/receipts/customers/{customer_id} Get the receipts for a customer scopes: - admin:receipts - read:receipts - user:receipts # Change customer_id Source: https://docs.dintero.com/api-reference/customer-receipts/aid_receipts_customers_cid_rid_change_customer_id_post /mintlify-docs/openapi/spec-receipts.yaml post /accounts/{aid}/receipts/customers/{customer_id}/{receipt_id}/change_customer_id Update customer_id for an receipt, i.e. move the receipt to a new customer > **warning**: The receipt will no longer be accessible > by the previous customer_id Following extra_info field will be added to the receipt when customer_id is changed using key - `dintero.receipts.change_customer_id.{timestamp}.{hash}` The content of the extra_info will be a JSON string containing: - created_at - created_by - old - new scopes: - admin:receipts # Customer receipt details Source: https://docs.dintero.com/api-reference/customer-receipts/aid_receipts_customers_cid_rid_get /mintlify-docs/openapi/spec-receipts.yaml get /accounts/{aid}/receipts/customers/{customer_id}/{receipt_id} Get a customer receipt scopes: - admin:receipts - read:receipts - user:receipts # Orders collection Source: https://docs.dintero.com/api-reference/customerorder/aid_customers_cid_orders_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/customers/{customer_id}/orders Retrieve a list of orders belonging to a customer user scopes: - user:shopping - admin:shopping - read:shopping # Get Order Source: https://docs.dintero.com/api-reference/customerorder/aid_customers_cid_orders_id_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/customers/{customer_id}/orders/{order_id} Retrieve Order details for an customer scopes: - user:shopping - admin:shopping - read:shopping # Get customer card details Source: https://docs.dintero.com/api-reference/customers/aid_customers_cid_card_cid_get /mintlify-docs/openapi/spec-wallets.yaml get /accounts/{aid}/wallets/customers/{customer_id}/cards/{card_id} Get all details about a customer card scopes: - admin:wallets - read:wallets - user:wallets # List customer cards Source: https://docs.dintero.com/api-reference/customers/aid_customers_cid_cards_get /mintlify-docs/openapi/spec-wallets.yaml get /accounts/{aid}/wallets/customers/{customer_id}/cards Get the cards active for a customer scopes: - admin:wallets - read:wallets - user:wallets # Complete a draft order Source: https://docs.dintero.com/api-reference/draft/aid_draft_orders_id_complete_put /mintlify-docs/openapi/spec-orders.yaml put /accounts/{aid}/shopping/draft_orders/{id}/complete Use this resource to transition the draft order into an Order. A draft with multiple sales locations will transition into one order per sales location. scopes: - admin:shopping - write:shopping # Get draft order Source: https://docs.dintero.com/api-reference/draft/aid_draft_orders_id_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/draft_orders/{id} Get draft order. scopes: - admin:shopping - read:shopping # Update draft order Source: https://docs.dintero.com/api-reference/draft/aid_draft_orders_id_put /mintlify-docs/openapi/spec-orders.yaml put /accounts/{aid}/shopping/draft_orders/{id} Updates a draft order. scopes: - admin:shopping - write:shopping # Create a draft order Source: https://docs.dintero.com/api-reference/draft/aid_draft_orders_post /mintlify-docs/openapi/spec-orders.yaml post /accounts/{aid}/shopping/draft_orders Use this resource to create orders in draft state. scopes: - admin:shopping - write:shopping # Remove item from draft Source: https://docs.dintero.com/api-reference/draftitems/aid_draft_orders_id_items_line_id_delete /mintlify-docs/openapi/spec-orders.yaml delete /accounts/{aid}/shopping/draft_orders/{id}/items/{line_id} Remove a item line from the draft scopes: - admin:shopping - write:shopping # Update item in draft Source: https://docs.dintero.com/api-reference/draftitems/aid_draft_orders_id_items_line_id_put /mintlify-docs/openapi/spec-orders.yaml put /accounts/{aid}/shopping/draft_orders/{id}/items/{line_id} Update item in draft scopes: - admin:shopping - write:shopping # Add item to draft Source: https://docs.dintero.com/api-reference/draftitems/aid_draft_orders_id_items_post /mintlify-docs/openapi/spec-orders.yaml post /accounts/{aid}/shopping/draft_orders/{id}/items Updates a draft with new item scopes: - admin:shopping - write:shopping # checkout_authorization Source: https://docs.dintero.com/api-reference/example-checkout-events/example_checkout_authorization_event /mintlify-docs/openapi/spec-webhooks.yaml post /examples/checkout_authorization Event is pushed to subscribers when a transaction was authorized or failed authorization > The deliveries match what is delivered to the session callback_url > with `report_error=true` set # checkout_token_* Source: https://docs.dintero.com/api-reference/example-checkout-events/example_checkout_token_event /mintlify-docs/openapi/spec-webhooks.yaml post /examples/checkout_token Event is pushed to subscribers when the checkout token is created, \ updated or deleted # checkout_transaction Source: https://docs.dintero.com/api-reference/example-checkout-events/example_checkout_transaction_event /mintlify-docs/openapi/spec-webhooks.yaml post /examples/checkout_transaction Event is pushed to subscribers when the checkout transaction is created or updated # approval_payout_destination_delete Source: https://docs.dintero.com/api-reference/example-management-auth-events/example_approval_payout_destination_update_delete /mintlify-docs/openapi/spec-webhooks.yaml post /examples/approval_payout_destination_delete Event is pushed to subscribers when the approval is archived # approval_payout_destination_update Source: https://docs.dintero.com/api-reference/example-management-auth-events/example_approval_payout_destination_update_event /mintlify-docs/openapi/spec-webhooks.yaml post /examples/approval_payout_destination_update Event is pushed to subscribers when the `case_status` of a seller approval changes # cdd_case_update Source: https://docs.dintero.com/api-reference/example-management-auth-events/example_cdd_case_update_event /mintlify-docs/openapi/spec-webhooks.yaml post /examples/cdd_case_update Event is pushed to subscribers when a CDD case changes status. Note that the event will only include one of `payout_destination_case` or `payment_case` never both # Discount codes Update Source: https://docs.dintero.com/api-reference/example-session-callbacks/example_discount_codes_callback_url /mintlify-docs/openapi/spec-payments.yaml post /examples/discount_code_callback_url This API endpoint on the merchant side allows Dintero to get shipping_options and order with discounts based on the provided session that had its `order.discount_codes` updated. # Session Callback Source: https://docs.dintero.com/api-reference/example-session-callbacks/example_session_post_callback_url /mintlify-docs/openapi/spec-payments.yaml post /examples/session_url_callback This API endpoint on the merchant side allows Dintero to notify the `session.url.callback_url` when the payment is completed > POST is only use if `callback_url` includes `method=POST` query parameter. > The `body` and `transaction_id` is optional if `report_error=true` # Address Update Source: https://docs.dintero.com/api-reference/example-session-callbacks/example_shipping_address_callback_url /mintlify-docs/openapi/spec-payments.yaml post /examples/shipping_address_callback_url This API endpoint on the merchant side allows Dintero to get shipping options based on the provided session after an address update # Client grants collection Source: https://docs.dintero.com/api-reference/grants/aid_auths_client_grants_get /mintlify-docs/openapi/spec-management-auth.yaml get /accounts/{oid}/auth/client-grants Manage your Client Grants (also called Client Credentials Grants). Using Client Grants, your Client can request an access token using its credentials (a Client ID and a Client Secret). The access token then represents your Client during API calls. Use the Grant type to limit how the grant can be used when requesting an access token. A Grant with type `password` can only be used when requesting an access token with grant_type set to `password`. scopes: - admin:accounts - read:accounts # Delete client grant Source: https://docs.dintero.com/api-reference/grants/aid_auths_client_grants_id_delete /mintlify-docs/openapi/spec-management-auth.yaml delete /accounts/{oid}/auth/client-grants/{id} scopes: - admin:accounts - write:accounts # Create client grant Source: https://docs.dintero.com/api-reference/grants/aid_auths_client_grants_post /mintlify-docs/openapi/spec-management-auth.yaml post /accounts/{oid}/auth/client-grants scopes: - admin:accounts - write:accounts # List checkout KPIs Source: https://docs.dintero.com/api-reference/kpi/api_insight_checkout_kpis_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/insight/kpi/checkout Get a list of KPIs where the transactiosn used is in the aggregations are transactions from "event_created_at_gte", until now. However, transactions from the "current" interval are not included.\ E.g if week is provided as interval, then no transactions from the current week are included. This is true for day and month intervals aswell. Scopes: - read:insight - admin:insight **deprecated** 2025-05-20 # Checkout transaction event KPIs Source: https://docs.dintero.com/api-reference/kpi/api_insight_checkout_transactions_events_kpis_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/insight/kpi/checkout-transaction-events Get a list of KPIs where the result is the aggregation of the specified event type given provided interval Scopes: - read:insight - admin:insight # Checkout transaction status KPIs Source: https://docs.dintero.com/api-reference/kpi/api_insight_checkout_transactions_status_kpis_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/insight/kpi/checkout-transaction-status Get a list of KPIs where the result is the aggregation of transactions where that match provided status Scopes: - read:insight - admin:insight # Delete location Source: https://docs.dintero.com/api-reference/locations/aid_location_lid_delete /mintlify-docs/openapi/spec-customers.yaml delete /accounts/{aid}/locations/{lid} Delete single location scopes: - admin:locations - write:locations # Update Sales location Source: https://docs.dintero.com/api-reference/locations/aid_location_lid_put /mintlify-docs/openapi/spec-customers.yaml put /accounts/{aid}/locations/{lid} Update location properties scopes: - admin:locations - write:locations # Create new sales location Source: https://docs.dintero.com/api-reference/locations/aid_location_post /mintlify-docs/openapi/spec-customers.yaml post /accounts/{aid}/locations Create a sales location scopes: - admin:locations - write:locations # Locations collection Source: https://docs.dintero.com/api-reference/locations/aid_locations_get /mintlify-docs/openapi/spec-customers.yaml get /accounts/{aid}/locations Get all sales locations, the starting_after have to be set to location_id scopes: - admin:locations - read:locations # Location details Source: https://docs.dintero.com/api-reference/locations/aid_locations_lid_get /mintlify-docs/openapi/spec-customers.yaml get /accounts/{aid}/locations/{lid} Get single sales location scopes: - admin:locations - read:locations # Get Order Source: https://docs.dintero.com/api-reference/order/aid_orders_id_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/orders/{order_id} Retrieve Order details scopes: - admin:shopping - read:shopping # Put Order Source: https://docs.dintero.com/api-reference/order/aid_orders_id_put /mintlify-docs/openapi/spec-orders.yaml put /accounts/{aid}/shopping/orders/{order_id} Update an order scopes: - admin:shopping - read:shopping # Get Authorization details Source: https://docs.dintero.com/api-reference/orderauthorizations/aid_orders_id_authorization_id_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/orders/{order_id}/authorizations/{authorization_id} Retrieve details about a authorization scopes: - admin:shopping - read:shopping # Create an authorization Source: https://docs.dintero.com/api-reference/orderauthorizations/aid_orders_id_authorization_post /mintlify-docs/openapi/spec-orders.yaml post /accounts/{aid}/shopping/orders/{order_id}/authorizations Create a authorization for an order scopes: - admin:shopping - write:shopping > An authorization event will be added to the order # Get Cancellation details Source: https://docs.dintero.com/api-reference/ordercancellations/aid_orders_id_cancellation_id_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/orders/{order_id}/cancellations/{cancellation_id} Retrieve details about a cancellation scopes: - admin:shopping - read:shopping # Create an cancellation Source: https://docs.dintero.com/api-reference/ordercancellations/aid_orders_id_cancellation_post /mintlify-docs/openapi/spec-orders.yaml post /accounts/{aid}/shopping/orders/{order_id}/cancellations Create a cancellation for an order scopes: - admin:shopping - write:shopping > An cancellation event will be added to the order # Create a capture Source: https://docs.dintero.com/api-reference/ordercaptures/aid_orders_id_capture_post /mintlify-docs/openapi/spec-orders.yaml post /accounts/{aid}/shopping/orders/{order_id}/captures Create a capture for an order scopes: - admin:shopping - write:shopping > A capture event will be added to the order # Get Capture details Source: https://docs.dintero.com/api-reference/ordercaptures/aid_orders_id_captures_id_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/orders/{order_id}/captures/{capture_id} Retrieve details about a capture scopes: - admin:shopping - read:shopping # Delete an order comment Source: https://docs.dintero.com/api-reference/ordercomments/aid_orders_id_comments_comment_id_delete /mintlify-docs/openapi/spec-orders.yaml delete /accounts/{aid}/shopping/orders/{order_id}/comments/{comment_id} Delete an order comment scopes: - admin:shopping - write:shopping # Create an order comment Source: https://docs.dintero.com/api-reference/ordercomments/aid_orders_id_comments_post /mintlify-docs/openapi/spec-orders.yaml post /accounts/{aid}/shopping/orders/{order_id}/comments Create a new order comment scopes: - admin:shopping - write:shopping # Create an order event Source: https://docs.dintero.com/api-reference/orderevents/aid_orders_id_events_post /mintlify-docs/openapi/spec-orders.yaml post /accounts/{aid}/shopping/orders/{order_id}/events Create a new order event scopes: - admin:shopping - write:shopping - write:shopping:/orders/ANY/events # Draft orders collection Source: https://docs.dintero.com/api-reference/orderlist/aid_draft_orders_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/draft_orders Retrieve a list of draft orders scopes: - admin:shopping - read:shopping # Orders collection Source: https://docs.dintero.com/api-reference/orderlist/aid_orders_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/orders Retrieve a list of orders scopes: - admin:shopping - read:shopping # Get Authorization Collection Source: https://docs.dintero.com/api-reference/orderlist/aid_orders_id_authorizations_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/orders/{order_id}/authorizations Retrieve list of authorizations for an order scopes: - admin:shopping - read:shopping # Get Cancellation Collection Source: https://docs.dintero.com/api-reference/orderlist/aid_orders_id_cancellations_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/orders/{order_id}/cancellations Retrieve list of cancellations for an order scopes: - admin:shopping - read:shopping # Get Capture Collection Source: https://docs.dintero.com/api-reference/orderlist/aid_orders_id_captures_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/orders/{order_id}/captures Retrieve list of captures for an order scopes: - admin:shopping - read:shopping # Order events collection Source: https://docs.dintero.com/api-reference/orderlist/aid_orders_id_events_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/orders/{order_id}/events Retrieve a list of latest order events scopes: - admin:shopping - read:shopping - read:shopping:/orders/ANY/events # Get Refunds Collection Source: https://docs.dintero.com/api-reference/orderlist/aid_orders_id_refunds_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/orders/{order_id}/refunds Retrieve list of refunds for an order scopes: - admin:shopping - read:shopping # Get Session Collection Source: https://docs.dintero.com/api-reference/orderlist/aid_orders_id_sessions_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/orders/{order_id}/sessions Retrieve list of sessions for an order scopes: - admin:shopping - read:shopping # Get Refunds details Source: https://docs.dintero.com/api-reference/orderrefunds/aid_orders_id_refunds_id_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/orders/{order_id}/refunds/{refund_id} Retrieve specific refund scopes: - admin:shopping - read:shopping # Create a refund Source: https://docs.dintero.com/api-reference/orderrefunds/aid_orders_id_refunds_post /mintlify-docs/openapi/spec-orders.yaml post /accounts/{aid}/shopping/orders/{order_id}/refunds Create a refund for an order scopes: - admin:shopping - write:shopping > A refund event will be added to the order # Create a session Source: https://docs.dintero.com/api-reference/ordersessions/aid_orders_id_session_post /mintlify-docs/openapi/spec-orders.yaml post /accounts/{aid}/shopping/orders/{order_id}/sessions Initiate a payment session for the order. scopes: - admin:shopping - write:shopping > A session event will be added to the order # Get Session details Source: https://docs.dintero.com/api-reference/ordersessions/aid_orders_id_sessions_id_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/orders/{order_id}/sessions/{session_id} Retrieve details about a session scopes: - admin:shopping - read:shopping # Cancel Order Source: https://docs.dintero.com/api-reference/orderstatus/aid_orders_id_cancel_post /mintlify-docs/openapi/spec-orders.yaml post /accounts/{aid}/shopping/orders/{order_id}/cancel Cancel the Order scopes: - admin:shopping - write:shopping > A cancel event will be added to the order # Close order Source: https://docs.dintero.com/api-reference/orderstatus/aid_orders_id_close_post /mintlify-docs/openapi/spec-orders.yaml post /accounts/{aid}/shopping/orders/{order_id}/close Close the order scopes: - admin:shopping - write:shopping > A close event will be added to the order # Open order Source: https://docs.dintero.com/api-reference/orderstatus/aid_orders_id_open_post /mintlify-docs/openapi/spec-orders.yaml post /accounts/{aid}/shopping/orders/{order_id}/open Re-open a closed order scopes: - admin:shopping - write:shopping > A open event will be added to the order # Get organization subunits Source: https://docs.dintero.com/api-reference/organizations/aid_get_external_organization_subunits /mintlify-docs/openapi/spec-customers.yaml get /accounts/{aid}/search/external/organizations/{country}/{organization_number}/subunits scopes: - public Get an organization's registered subunits. Proxies queries to respective registers. Currently only Norway (`no`) organization numbers are supported. # Get addresses for organization number from external organization registry Source: https://docs.dintero.com/api-reference/organizations/aid_get_external_organizations /mintlify-docs/openapi/spec-customers.yaml get /accounts/{aid}/search/external/organizations/{country}/{organization_number} scopes: - public # Search external organization registry Source: https://docs.dintero.com/api-reference/organizations/aid_search_external_organizations_country /mintlify-docs/openapi/spec-customers.yaml get /accounts/{aid}/search/external/organizations/{country} Proxy queries to the Norwegian or Danish organization registry. Please note that the only supported countries currently are "no" (Norway) and "dk" (Denmark). scopes: - public # Change password Source: https://docs.dintero.com/api-reference/password/aid_customers_change_password /mintlify-docs/openapi/spec-customers.yaml post /accounts/{aid}/customers/change_password Specify the email address of the user whose password you would like to reset. If the call is successful, the user will receive an email prompting them to change their password. The caller must have scope `write:accounts:/auth/users` to perform a change password request. scopes: - write:accounts:/auth/users # Login with email/password Source: https://docs.dintero.com/api-reference/password/aid_customers_login_post /mintlify-docs/openapi/spec-customers.yaml post /accounts/{aid}/customers/login Login a customer user, the caller must have scope `write:accounts:/auth/users`. If MFA is enabled on account, use `write:accounts:/auth/users/no-mfa` to skip MFA. scopes: - write:accounts:/auth/users - write:accounts:/auth/users/no-mfa # MFA recovery Source: https://docs.dintero.com/api-reference/password/aid_customers_mfa_login_initiate_recovery_post /mintlify-docs/openapi/spec-customers.yaml post /accounts/{aid}/customers/mfa_login_recovery Initiate a Multi-Factor Authentication recovery login for a customer user that has forgotten/lost their `secret`. Specify the ident_type and the ident (email or phone_number) of the user. If the call is successful, the user will get an email with an one time recovery code that has to be submitted to the mfa_recovery endpoint. When a valid one time recovery has been posted the server response with a regular MFA challenge. Once authenticated the password or pin can be changed by updating the customer. scopes: - write:accounts:/auth/users # Login with MFA Source: https://docs.dintero.com/api-reference/password/aid_customers_mfa_login_post /mintlify-docs/openapi/spec-customers.yaml post /accounts/{aid}/customers/mfa_login Initiate a Multi-Factor Authentication for a customer user, the caller must have scope `write:accounts:/auth/users` to perform a login. Post the `ident_type`, along with the `ident` and `secret`. The server will return a challenge response specifying the `challenge_type` that will have to be completed to when getting an access token from the `POST /v1/accounts/{oid}/auth/token` endpoint. scopes: - write:accounts:/auth/users # Create and pay merchant initiated session Source: https://docs.dintero.com/api-reference/payment/checkout_session_pay_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/payments/sessions/pay For merchant initiated payments, where the customer is not involved. Receives a session and pays it with the given card token. > Merchant is resposible for managing their retry policy for payments > that fails, and not retry when payment fails with `DO_NOT_RETRY` error. > > 200 response will be returned when request fails due to authorization error. Transaction > will have status `FAILED` and error information can be found at `events.error`. > > Insufficient error handling will cause cards to be blocked > https://docs.dintero.com/docs/checkout/tokenization#do-not-try-again--excessive-reattempts scopes: - admin:checkout - write:checkout # Initiate a checkout payment Source: https://docs.dintero.com/api-reference/payment/checkout_sid_pay_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/payments/sessions/{session_id}/pay For Express Checkout sessions, the _`order.shipping_address`_ must be set on the session, and a _`order.items.shipping_option` item is required if the session has either an _`express.shipping_address_callback_url`_ or the session has at least one option in _`express.shipping_options`_. # List payout destinations Source: https://docs.dintero.com/api-reference/payout-destinations/aid_mgmnt_payout_destinations_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{oid}/payout-destinations Get list of payout destinations scopes: - admin:accounts - read:accounts # Get payout destination Source: https://docs.dintero.com/api-reference/payout-destinations/aid_mgmnt_payout_destinations_get_by_id /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{oid}/payout-destinations/{payout_destination_id} Get a payout destination by payout destination id scopes: - admin:accounts - read:accounts # Create payout destination Source: https://docs.dintero.com/api-reference/payout-destinations/aid_mgmnt_payout_destinations_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{oid}/payout-destinations Create a payout destination for an account Dintero admins (access tokens with the `admin:dintero` scope) can replace Dintero's standard terms for sellers with links to custom agreements by supplying `custom_agreements`. A case created with `custom_agreements` is always reviewed manually, it is never approved automatically. scopes: - admin:accounts - write:accounts - write:accounts:/management/settings/approvals # Update payout destination Source: https://docs.dintero.com/api-reference/payout-destinations/oid_mgmnt_payout_destinations_by_id_patch /mintlify-docs/openapi/spec-payments-v2.yaml patch /accounts/{oid}/payout-destinations/{payout_destination_id} Update a payout destination. Currently only allows update of `payout_interval_type`. scopes: - admin:accounts - write:accounts # Fund transfer Source: https://docs.dintero.com/api-reference/payout-destinations/oid_mgmnt_payout_destinations_fund-transfers_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{oid}/payout-destinations/{payout_destination_id}/fund-transfers Initiate a fund transfer from the current payout destination to another payout destination. Currently only same-account fund transfers are supported. Requests for fund transfers are processed asynchronously, so in the response we only inform you that we received a valid request. You will get the result in the settlement report. scopes: - write:payout - admin:payout - write:accounts:/fund-transfers # On-demand payout Source: https://docs.dintero.com/api-reference/payout-destinations/oid_mgmnt_payout_destinations_payouts_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{oid}/payout-destinations/{payout_destination_id}/payouts Create a payout for the given payout destination by consolidating all pending funds from any payout interval account (week, month) into the daily payout account. The funds will then be included in the next daily payout run. This is useful when you want existing pending payouts to be disbursed without waiting for the original schedule, or when you want to manually trigger a payout outside the normal interval. scopes: - write:accounts:/on-demand-payouts # Create new Receipts Source: https://docs.dintero.com/api-reference/receipts/aid_receipts_post /mintlify-docs/openapi/spec-receipts.yaml post /accounts/{aid}/receipts Post receipts scopes: - admin:receipts - write:receipts # Get receipt by token Source: https://docs.dintero.com/api-reference/receipts/aid_receipts_receipt_token_get /mintlify-docs/openapi/spec-receipts.yaml get /accounts/{aid}/receipts/receipt-token Get receipt from token. The token must be a signed JWT token containing the `customer_id` and `receipt_id` to fetch. scopes: - admin:receipts - read:receipts - user:receipts - public:receipts # Claim receipt by token Source: https://docs.dintero.com/api-reference/receipts/aid_receipts_receipt_token_post /mintlify-docs/openapi/spec-receipts.yaml post /accounts/{aid}/receipts/receipt-token Update `customer_id` on receipt identified by token. The token will be invalid after the claim. scopes: - admin:receipts - write:receipts - user:receipts # Receipt search Source: https://docs.dintero.com/api-reference/receipts/aid_receipts_rid_get /mintlify-docs/openapi/spec-receipts.yaml get /accounts/{aid}/receipts/search Get receipts matching receipt_id (POS id) scopes: - admin:receipts - read:receipts # Update receipt Source: https://docs.dintero.com/api-reference/receipts/aid_receipts_update_put /mintlify-docs/openapi/spec-receipts.yaml put /accounts/{aid}/receipts/all/{receipt_id} Update existing anonymous receipt. ### Limitation - update of customer_id is only allowed if the current customer_id is null. - update of discounts is only allowed if current discounts value is null or empty scopes: - admin:receipts - read:receipts # Create new insight report configuration Source: https://docs.dintero.com/api-reference/report-configuration/aid_report_configuration_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/insight/reports/configuration Create a new report configuration scopes: - write:insight - admin:insight # Delete insight report configuration Source: https://docs.dintero.com/api-reference/report-configuration/aid_reports_configuration_delete /mintlify-docs/openapi/spec-payments-v2.yaml delete /accounts/{aid}/insight/reports/configuration/{id} Delete insight report configuration. scopes: - write:insight - admin:insight # List insight configurations Source: https://docs.dintero.com/api-reference/report-configuration/aid_reports_configuration_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/insight/reports/configuration List all insight report configurations for the account. scopes: - read:insight - admin:insight # Update insight report configuration Source: https://docs.dintero.com/api-reference/report-configuration/aid_reports_configuration_put /mintlify-docs/openapi/spec-payments-v2.yaml put /accounts/{aid}/insight/reports/configuration/{id} Update insight report configuration. Scopes: - write:insight - admin:insight # List report metadata Source: https://docs.dintero.com/api-reference/reports/api_reports_metadata_list_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/reports/metadata Get list of report metadata for the account Scopes: - read:reports - admin:reports # Automation collection Source: https://docs.dintero.com/api-reference/rules-automations/aid_automations_rules_get /mintlify-docs/openapi/spec-discounts.yaml get /accounts/{aid}/automations/rules Get available automations for the account scopes: - admin:automations - read:automations # Create new automation Source: https://docs.dintero.com/api-reference/rules-automations/aid_automations_rules_post /mintlify-docs/openapi/spec-discounts.yaml post /accounts/{aid}/automations/rules Create a discount automation to apply on events received. A automation can be used to automate the task of giving discount to customers. The customer found in the event will receive the discount. ### Welcome discount: give discount to new user { "requirement": { "events": ["customer_add"], "automation_from": "2018-05-07T08:54:31Z", "automation_to": "2018-06-07T08:54:31Z" }, "actions": [ { "type": "discount", "id": "cae3e485-0e15-4afa-bc66-472f843efb84" } ] } ### Purchase discount: give discount on first purchase at store { "name": "purchase at store sc029", "requirement": { "events": ["receipt_add"], "automation_from": "2018-05-07T08:54:31Z", "automation_to": "2018-06-07T08:54:31Z", "filters": { "$.store.id": ["sc029"] } }, "actions": [ { "type": "discount", "id": "cae3e485-0e15-4afa-bc66-472f843efb84" } ], "limitation": { "automation_repeat": 1 } } scopes: - admin:automations - write:automations # Delete automation Source: https://docs.dintero.com/api-reference/rules-automations/aid_automations_rules_rid_delete /mintlify-docs/openapi/spec-discounts.yaml delete /accounts/{aid}/automations/rules/{arid} Delete an automation rule. scopes: - admin:automations - write:automations # Automation details Source: https://docs.dintero.com/api-reference/rules-automations/aid_automations_rules_rid_get /mintlify-docs/openapi/spec-discounts.yaml get /accounts/{aid}/automations/rules/{arid} Get details about an automations scopes: - admin:automations - read:automations # Delete customer discount ref Source: https://docs.dintero.com/api-reference/rules-customers/aid_discounts_customer_cid_delete_ref_id /mintlify-docs/openapi/spec-discounts.yaml delete /accounts/{aid}/discounts/customers/{customer_id}/refs/{ref_id} Delete a customer discount ref. The discount will no longer be available on purchase ([Post receipt for discount](/discounts-api/use-discounts/aid_discounts_available_for_receipt_post)) scopes: - admin:discounts - write:discounts # Customer discounts collection Source: https://docs.dintero.com/api-reference/rules-customers/aid_discounts_customer_cid_get /mintlify-docs/openapi/spec-discounts.yaml get /accounts/{aid}/discounts/customers/{customer_id}/rules Get all discounts available for a customer, result will exclude expired and inactive discounts Expired discounts are: - discount used up (customer has allready used it) and there was a limitation on the discount that prevents more use. - discount requirement purchase periode is in the past - discount that has been deleted Inactive discounts are: - discount with `active` property set to false. Use value of `ref_id` as parameter value of `starting_after` scopes: - admin:discounts - read:discounts - user:discounts # Get customer discount ref Source: https://docs.dintero.com/api-reference/rules-customers/aid_discounts_customer_cid_get_ref_id /mintlify-docs/openapi/spec-discounts.yaml get /accounts/{aid}/discounts/customers/{customer_id}/refs/{ref_id} Get a customer discount ref. scopes: - admin:discounts - read:discounts # Update customer discount ref Source: https://docs.dintero.com/api-reference/rules-customers/aid_discounts_customer_cid_post_ref_id /mintlify-docs/openapi/spec-discounts.yaml post /accounts/{aid}/discounts/customers/{customer_id}/refs/{ref_id} Add stamps and usage to a discount ref. scopes: - admin:discounts - write:discounts # Remove customers Source: https://docs.dintero.com/api-reference/rules-customers/aid_discounts_did_customers_delete /mintlify-docs/openapi/spec-discounts.yaml delete /accounts/{aid}/discounts/rules/{did}/customers Remove Discount from one or more customers scopes: - admin:discounts - write:discounts # Get discount customers (refs) Source: https://docs.dintero.com/api-reference/rules-customers/aid_discounts_did_customers_get /mintlify-docs/openapi/spec-discounts.yaml get /accounts/{aid}/discounts/rules/{did}/customers Get list of customers refs for a discount. A ref is an instant of discount given to a customer or `all customers`. See [Add customers](/discounts-api/rules-customers/aid_discounts_did_customers_post) scopes: - admin:discounts - read:discounts # Add customers Source: https://docs.dintero.com/api-reference/rules-customers/aid_discounts_did_customers_post /mintlify-docs/openapi/spec-discounts.yaml post /accounts/{aid}/discounts/rules/{did}/customers Give the Discount to one or more customers scopes: - admin:discounts - write:discounts # Get discount ref usages Source: https://docs.dintero.com/api-reference/rules-customers/aid_discounts_did_usages_get /mintlify-docs/openapi/spec-discounts.yaml get /accounts/{aid}/discounts/rules/{did}/usages Get list of discount refs usages. scopes: - admin:discounts - read:discounts # Delete discount Source: https://docs.dintero.com/api-reference/rules/aid_discounts_did_delete /mintlify-docs/openapi/spec-discounts.yaml delete /accounts/{aid}/discounts/rules/{did} Delete a discount - Customer that has previously received the discount will not be able to use it on purchases. - rules automations belonging to the discount will be deleted scopes: - admin:discounts - write:discounts # Discount details Source: https://docs.dintero.com/api-reference/rules/aid_discounts_did_get /mintlify-docs/openapi/spec-discounts.yaml get /accounts/{aid}/discounts/rules/{did} Get more details about a discount, includes statistics about the discount scopes: - admin:discounts - read:discounts # Update Discount Source: https://docs.dintero.com/api-reference/rules/aid_discounts_did_put /mintlify-docs/openapi/spec-discounts.yaml put /accounts/{aid}/discounts/rules/{did} Update discount details. **Caution**: Update of non-meta properties, properties that changes requirement or limitation can create conflict with the usage history of the discount. Example is to change requirement.item.items, such change would mean that purchases before the change would not be correctly rewarded given the new version of the discount. We recommend to limit the update of a discount to meta only properties if the discount has previously been used in a purchase. Update on requirement `purchase_to` is only supported when the new value that is after current value. `purchase_from` can not be updated. Changing `purchase_to` or `limitation.dynamic_purchase_to_days` also updates the customer discounts already given, and is only supported with `mode=merge`. `reward` can be updated. The replace rules are described in the `reward` property of the request body. `requirement` and `limitation` keys are merged with the current values. Use `mode=replace` to replace the rule, for example to remove a key. The discount `type` (receipt/item) is derived from the updated `requirement.item`. The reward of a `discount_debit` discount can not be changed, and a reward can not be changed to `discount_debit`. Only `reward.base` can be updated. Update `discount.active` to toggle if an discount is active and available for purchase. Update `discount.private` to toggle if an discount is included in public discount collection if given to all customers scopes: - admin:discounts - write:discounts # Discount collection Source: https://docs.dintero.com/api-reference/rules/aid_discounts_get /mintlify-docs/openapi/spec-discounts.yaml get /accounts/{aid}/discounts/rules List discounts available for the account scopes: - admin:discounts - read:discounts # Create new discount Source: https://docs.dintero.com/api-reference/rules/aid_discounts_post /mintlify-docs/openapi/spec-discounts.yaml post /accounts/{aid}/discounts/rules Create a new discount for an account. A new discount will be **unavailable** for purchases until the discount is given to one or more customer. Discount can be given to a customer by either adding a automation to the discount that will grant the discount to the customer from events received or by adding customers to the discount. See [Discount Examples](#section/Discount-Examples) scopes: - admin:discounts - write:discounts # Public Discount collection Source: https://docs.dintero.com/api-reference/rules/aid_discounts_public_get /mintlify-docs/openapi/spec-discounts.yaml get /accounts/{aid}/discounts/public/rules Get all discounts available for any customer given current date, result will exclude expired and inactive discounts Use value of `ref_id` as parameter value of `starting_after` scopes: - admin:discounts - read:discounts - public:discounts # Search for discount rules Source: https://docs.dintero.com/api-reference/rules/aid_discounts_rules_search_post /mintlify-docs/openapi/spec-discounts.yaml post /accounts/{aid}/discounts/search/rules Search for active discounts given current date matching queries scopes: - admin:discounts - read:discounts # Customer segmentation Source: https://docs.dintero.com/api-reference/segment/aid_receipts_customer_segment_post /mintlify-docs/openapi/spec-receipts.yaml post /accounts/{aid}/receipts/customer_segment Segment customer by receipt data scopes: - admin:receipts - read:receipts # Payment token session Source: https://docs.dintero.com/api-reference/session/checkout_payment_token_session_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/payments/sessions/payment-token This endpoint lets you create payment and recurrence tokens without reserving or charging any amount. The URL returned by this endpoint opens a web site where the customer can enter their payment details, e.g. card information. The payment details will be validated and a transaction with a payment/recurrence token will be created on success containing the payment token created from the customer payment details. - [GET /v1/transactions/{id}?includes=card.payment_token](/api-reference/default/transactions_id_get) - [GET /v1/transactions/{id}?includes=card.recurrence_token](/api-reference/default/transactions_id_get) scopes: - admin:checkout - write:checkout # Cancel session Source: https://docs.dintero.com/api-reference/session/checkout_session_cancel_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/payments/sessions/{session_id}/cancel Cancel a session The session transaction will be voided in case where it is initialized or authorized. Cancel is not allowed in case where the current transaction state is not initialized or authorized. scopes: - admin:checkout - write:checkout # Get checkout session details Source: https://docs.dintero.com/api-reference/session/checkout_session_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/payments/sessions/{session_id} scopes: - admin:checkout - read:checkout # Create checkout session from profile Source: https://docs.dintero.com/api-reference/session/checkout_session_profile_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/payments/sessions-profile Create a corresponding Checkout Session for an order placed in your system using predefined session profile #### Session with Instabank Note that `items` is a required property when creating a session with Instabank configured. scopes: - admin:checkout - write:checkout # Update checkout session details Source: https://docs.dintero.com/api-reference/session/checkout_session_put /mintlify-docs/openapi/spec-payments-v2.yaml put /accounts/{aid}/payments/sessions/{session_id} Session must be locked for paying before updating. **Requirements**: - `order.shipping_option` must be included in `express_shipping_options` if both are set. - `order.amount` must be equal to the sum of `order.items` and `order.shipping_option` scopes: - admin:checkout - read:checkout # Customers settings Source: https://docs.dintero.com/api-reference/settings/aid_customers_atributes_get /mintlify-docs/openapi/spec-customers.yaml get /accounts/{aid}/customers/settings Get customers settings scopes: - admin:customers - read:customers - public:customers # Update settings Source: https://docs.dintero.com/api-reference/settings/aid_customers_atributes_put /mintlify-docs/openapi/spec-customers.yaml put /accounts/{aid}/customers/settings Update customers settings scopes: - admin:customers - write:customers # Generate a test settlement report Source: https://docs.dintero.com/api-reference/settlements/aid_settlement_generate_test_report /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/settlements/reports/generate-test-report Generate a test settlement report. Only available in test. *scopes*: - admin:billing - admin:reports # List settlements Source: https://docs.dintero.com/api-reference/settlements/aid_settlements_list /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/settlements List settlements *scopes*: - admin:billing - read:billing - admin:reports - read:reports - admin:settlements - read:settlements # Download attachment Source: https://docs.dintero.com/api-reference/settlements/settlement_attachment_download /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/settlements/{settlementid}/attachments/{attachmentid} Download a settlement attachment *scopes*: - admin:billing - read:billing - admin:reports - read:reports - admin:settlements - read:settlements # Create settlement report configurations Source: https://docs.dintero.com/api-reference/settlementsconfiguration/aid_settlement_report_config_create /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/settlements/reports/configuration Create settlement report configurations *scopes*: - admin:billing - admin:reports - admin:settlements - write:settlements # Delete settlement report configuration Source: https://docs.dintero.com/api-reference/settlementsconfiguration/aid_settlement_report_config_delete /mintlify-docs/openapi/spec-payments-v2.yaml delete /accounts/{aid}/settlements/reports/configuration/{id} Delete settlement report configuration *scopes*: - admin:billing - write:billing - admin:settlements - write:settlements # Get settlement report configuration Source: https://docs.dintero.com/api-reference/settlementsconfiguration/aid_settlement_report_config_details /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/settlements/reports/configuration/{id} Get settlement report configuration *scopes*: - admin:billing - read:billing - admin:reports - read:reports - admin:settlements - read:settlements # List settlement report configurations Source: https://docs.dintero.com/api-reference/settlementsconfiguration/aid_settlement_report_config_list /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/settlements/reports/configuration List settlement report configurations *scopes*: - admin:billing - read:billing - admin:reports - read:reports - admin:settlements - read:settlements # Update settlement report configuration Source: https://docs.dintero.com/api-reference/settlementsconfiguration/aid_settlement_report_config_update /mintlify-docs/openapi/spec-payments-v2.yaml put /accounts/{aid}/settlements/reports/configuration/{id} Update settlement report configuration *scopes*: - admin:billing - write:billing - admin:settlements - write:settlements # Orders collection Source: https://docs.dintero.com/api-reference/storeorder/aid_stores_sid_orders_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/stores/{store_id}/orders Retrieve a list of orders belonging to a store scopes: - admin:shopping - read:shopping # Get Order Source: https://docs.dintero.com/api-reference/storeorder/aid_stores_sid_orders_id_get /mintlify-docs/openapi/spec-orders.yaml get /accounts/{aid}/shopping/stores/{store_id}/orders/{order_id} Retrieve Order details belonging to a store scopes: - admin:shopping - read:shopping # Tag collection Source: https://docs.dintero.com/api-reference/tags/aid_customers_cid_tags_get /mintlify-docs/openapi/spec-customers.yaml get /accounts/{aid}/customers/users/{customer_id}/tags Get tags for a customer scopes: - admin:customers - read:customers - user:customers # Update Customer Tags Source: https://docs.dintero.com/api-reference/tags/aid_customers_cid_tags_put /mintlify-docs/openapi/spec-customers.yaml put /accounts/{aid}/customers/users/{customer_id}/tags Update Customer Tags scopes: - admin:customers - write:customers - user:customers # Tags collection Source: https://docs.dintero.com/api-reference/tags/aid_customers_tags_get /mintlify-docs/openapi/spec-customers.yaml get /accounts/{aid}/customers/tags Get all customer tags (also known as groups). scopes: - admin:customers - read:customers # Create new Tag Source: https://docs.dintero.com/api-reference/tags/aid_customers_tags_post /mintlify-docs/openapi/spec-customers.yaml post /accounts/{aid}/customers/tags Create a tag scopes: - admin:customers - write:customers # Delete Tag Source: https://docs.dintero.com/api-reference/tags/aid_customers_tags_tid_delete /mintlify-docs/openapi/spec-customers.yaml delete /accounts/{aid}/customers/tags/{tag_id} Delete a tag. A deleted tag is removed from customer tags scopes: - admin:customers - write:customers # List terminal operation results Source: https://docs.dintero.com/api-reference/terminals/admin_terminals_operations_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/payments/admin/terminals/operations List administrative operations sent to any of the account's terminals, most recently created first. Filter to a single terminal with `terminal_id`, or a single operation with `operation_id`. Poll this endpoint to see how a command finished: an operation is created as PENDING and reaches COMPLETED, FAILED or TIMEOUT once the terminal answers or the timeout window passes. The `result` of a completed operation is specific to the operation that was run. scopes: - admin:checkout - read:checkout:/admin/terminals # Post terminal operation Source: https://docs.dintero.com/api-reference/terminals/admin_terminals_operations_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/payments/admin/terminals/operations Send an administrative command to a payment terminal. These commands do not start a payment. The response is returned immediately after the command is dispatched to the terminal, with status PENDING. The terminal's response is processed asynchronously. Use [GET /admin/terminals/operations](/api-reference/terminals/admin_terminals_operations_get) to see how the operation finished. While another operation of the same type is pending on the terminal, 409 is returned. Each operation also requires the terminal to be in a suitable status. The `operation` field below lists the status for each. The request is rejected with 400 when the status does not allow it. scopes: - admin:checkout - write:checkout:/admin/terminals # Trigger terminal activation Source: https://docs.dintero.com/api-reference/terminals/admin_terminals_terminal_id_activations_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/payments/admin/terminals/{terminal_id}/activations Activate a terminal. Confirms the terminal is reachable and moves it into an active, ready-to-use state. Call this once the terminal has been physically set up. scopes: - admin:checkout - write:checkout:/admin/terminals # Terms collection Source: https://docs.dintero.com/api-reference/terms/aid_customers_terms_get /mintlify-docs/openapi/spec-customers.yaml get /accounts/{aid}/customers/terms Get all customer terms and conditions scopes: - admin:customers - read:customers - public:customers # Create new Terms Source: https://docs.dintero.com/api-reference/terms/aid_customers_terms_post /mintlify-docs/openapi/spec-customers.yaml post /accounts/{aid}/customers/terms Create customer terms and conditions scopes: - admin:customers - write:customers # Delete Term Source: https://docs.dintero.com/api-reference/terms/aid_customers_terms_tid_delete /mintlify-docs/openapi/spec-customers.yaml delete /accounts/{aid}/customers/terms/{tid} Delete the customer term scopes: - admin:customers - write:customers # Terms details Source: https://docs.dintero.com/api-reference/terms/aid_customers_terms_tid_post /mintlify-docs/openapi/spec-customers.yaml get /accounts/{aid}/customers/terms/{tid} Get single terms and conditions scopes: - admin:customers - read:customers - public:customers # Token collections Source: https://docs.dintero.com/api-reference/tokens/aid_customers_cid_tokens_get /mintlify-docs/openapi/spec-customers.yaml get /accounts/{aid}/customers/users/{customer_id}/tokens Get all tokens for a Customer scopes: - admin:customers - read:customers - user:customers # Create new Token Source: https://docs.dintero.com/api-reference/tokens/aid_customers_cid_tokens_post /mintlify-docs/openapi/spec-customers.yaml post /accounts/{aid}/customers/users/{customer_id}/tokens Create a new customer token scopes: - admin:customers - write:customers - user:customers # Delete customer token Source: https://docs.dintero.com/api-reference/tokens/aid_customers_cid_tokens_tid_delete /mintlify-docs/openapi/spec-customers.yaml delete /accounts/{aid}/customers/users/{customer_id}/tokens/{tid} Delete Token scopes: - admin:customers - write:customers - user:customers # Delete token events Source: https://docs.dintero.com/api-reference/tokens/aid_customers_tokens_events_delete /mintlify-docs/openapi/spec-customers.yaml delete /accounts/{aid}/customers/tokens/events Delete the connection between token (type/value) and list of events. Include an event in the request to store the reason for the request scopes: - admin:customers - write:customers # Get token events Source: https://docs.dintero.com/api-reference/tokens/aid_customers_tokens_events_get /mintlify-docs/openapi/spec-customers.yaml get /accounts/{aid}/customers/tokens/events Get the token events scopes: - admin:customers - read:customers # Find / Add token events Source: https://docs.dintero.com/api-reference/tokens/aid_customers_tokens_events_post /mintlify-docs/openapi/spec-customers.yaml post /accounts/{aid}/customers/tokens/events Find details about a token, inclusive details about any customer the token belongs to and any token events recorded Include event in the request to update the status of the token scopes: - admin:customers - write:customers # Capture pending transaction Source: https://docs.dintero.com/api-reference/transactions/aid_cards_cardid_transactions_capture_post /mintlify-docs/openapi/spec-wallets.yaml post /accounts/{aid}/wallets/transactions/{transaction_id}/capture Capture a pending Transaction, thereby collection the amount withheld by the pending transaction. Option to specify an amount that should be captured. Defaults to capture the full transaction. When the amount specified is less than the reserved/pending, the remaining amount will still be reserved/pending and can be captured later. scopes: - admin:wallets - write:wallets - write:wallets:/transactions # List card transactions Source: https://docs.dintero.com/api-reference/transactions/aid_cards_cardid_transactions_tid_get /mintlify-docs/openapi/spec-wallets.yaml get /accounts/{aid}/wallets/cards/{card_id}/transactions Retrieve a list of Card's Transaction based on card id scopes: - admin:wallets - read:wallets # Void pending transaction Source: https://docs.dintero.com/api-reference/transactions/aid_cards_cardid_transactions_void_post /mintlify-docs/openapi/spec-wallets.yaml post /accounts/{aid}/wallets/transactions/{transaction_id}/void Void a pending Transaction by unlocking the amount withheld by the pending transaction scopes: - admin:wallets - write:wallets - write:wallets:/transactions # Create transaction Source: https://docs.dintero.com/api-reference/transactions/aid_cards_transactions_post /mintlify-docs/openapi/spec-wallets.yaml post /accounts/{aid}/wallets/transactions Create a transaction against a Card using `token` or `card_id`. If the Transactions is created as pending, the value will be locked until it is either captured or voided. Transaction ID must be used when capturing or voiding a transaction. > Using **`card_id`** or creating a **`fund`** transaction requires > authorization scope `admin:wallets` or `write:wallets` scopes: - admin:wallets - write:wallets - write:wallets:/transactions # Update transaction authorization Source: https://docs.dintero.com/api-reference/transactions/transaction_tid_extend_authorization_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/payments/transactions/{id}/authorization This endpoint is used to update an existing authorization: **Use cases:** 1. **Extend authorization (Klarna)** - Provider: `klarna` - Purpose: Extend the lifetime of an existing authorization. - Required fields: - `reason` (string): The reason for the extension. - `reference` (string): A reference specified by the merchant to identify the transaction. 2. **Update order amount (Klarna)** - Provider: `klarna` - Purpose: Update the authorized amount for an existing Klarna order. - Required fields: - `amount` (number): The new amount to authorize. - `items` (array): List of transaction items. Sum of item amounts must equal the updated transaction amount. - `description` (string): Optional description of the order. - `reason` (string): Optional reason for the update. - `reference` (string): Optional merchant reference to identify the transaction. 3. **Update pre-authorization (Dintero PSP)** - Provider: `dintero_psp` - Purpose: Update the pre-authorized amount and/or finalize the authorization. - Required fields: - `amount` (number): The new amount to authorize. - If `final_authorization=false`, the new amount **must be greater than** the previous pre-authorized amount. - If `final_authorization=true`, the amount **may be increased, reduced, or unchanged**. - `final_authorization` (boolean): Indicates whether this is the final authorization step. - `true`: Finalizes the authorization and locks the transaction for further updates. - `false`: Keeps the pre-authorization open for future updates. - `reference` (string): Optional merchant reference to identify the transaction. - `items` (array): Optional list of transaction items to update. If the transaction already has items, this field is required. When present, sum of item amounts must equal the updated transaction amount. 4. **Authorize external transaction (Dintero External)** - Provider: `dintero` - Purpose: Authorize a transaction currently on hold. - If `amount` or `items` are provided, the API will validate if the details are consistent with the order in the transaction. --- **Notes:** - For Klarna: - If `amount` is **not provided**: Extend authorization flow is used (use case 1). Only `reason` and `reference` are relevant. - If `amount` **is provided**: Update order amount flow is used (use case 2). `amount` is required; `items` and `description` are optional. - For pre-authorization: Only `amount`, `final_authorization`, and `reference` are relevant. # List all transactions Source: https://docs.dintero.com/api-reference/transactions/transactions_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/payments/transactions scopes: - admin:checkout - read:checkout # Capture a transaction Source: https://docs.dintero.com/api-reference/transactions/transactions_id_capture_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/payments/transactions/{id}/capture Captures a transaction that was created with the Checkout endpoint with a `capture_now` value of `false`. #### Capture Instabank transaction Note that `items` is required when capturing a transaction with `payment_product=instabank`. The items must include the lines to Capture, with `line_id`, `quantity` and `amount`. scopes: - admin:checkout - write:checkout # Get a transaction Source: https://docs.dintero.com/api-reference/transactions/transactions_id_get /mintlify-docs/openapi/spec-payments-v2.yaml get /accounts/{aid}/payments/transactions/{id} scopes: - admin:checkout - read:checkout # Update a transaction Source: https://docs.dintero.com/api-reference/transactions/transactions_id_put /mintlify-docs/openapi/spec-payments-v2.yaml put /accounts/{aid}/payments/transactions/{id} scopes: - admin:checkout - write:checkout # Refund transaction Source: https://docs.dintero.com/api-reference/transactions/transactions_id_refund_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/payments/transactions/{id}/refund Once a transaction has been successfully captured, a refund operation is available. Like other operations, refund can be partial or total #### Refund Instabank transaction Note that `items` is required when refunding a transaction with `payment_product=instabank`. The items must include the lines to Refund, with `line_id`, `quantity` and `amount`. #### Refund `seitatech.in_person` transaction `terminal_id` is required when refunding a `seitatech.in_person` transaction. The cardholder must be present to approve the refund on a terminal active on the same `payout_destination_id` as the original transaction. scopes: - admin:checkout - write:checkout # Void transaction Source: https://docs.dintero.com/api-reference/transactions/transactions_id_void_post /mintlify-docs/openapi/spec-payments-v2.yaml post /accounts/{aid}/payments/transactions/{id}/void At any moment before capture of a transaction, it is possible to cancel an authorization. This operation is called voiding and can be performed by doing a POST to this endpoint #### Void on part capture Void after a part capture will cancel the difference between the capture amount and the authorization amount. Void on part capture is only supported on following types: - `payex.creditcard` - `payex.mobilepay` - `payex.vipps` - `payex.applepay` - `payex.clicktopay` - `payex.googlepay` - `vipps` - `klarna.klarna` - `klarna.billie` scopes: - admin:checkout - write:checkout # Delete claim Source: https://docs.dintero.com/api-reference/use-discounts/aid_discounts_available_for_receipt_delete_claim /mintlify-docs/openapi/spec-discounts.yaml delete /accounts/{aid}/discounts/available_for_receipt/claims/{claim_id} Release claim on discounts, revert previously claimed discount and make them available for future purchase scopes: - admin:discounts - write:discounts - write:discounts:/available_for_receipt # Get claim Source: https://docs.dintero.com/api-reference/use-discounts/aid_discounts_available_for_receipt_get_claim /mintlify-docs/openapi/spec-discounts.yaml get /accounts/{aid}/discounts/available_for_receipt/claims/{claim_id} Get details about a claim scopes: - admin:discounts - read:discounts - read:discounts:/available_for_receipt # Claim collections Source: https://docs.dintero.com/api-reference/use-discounts/aid_discounts_available_for_receipt_get_claims /mintlify-docs/openapi/spec-discounts.yaml get /accounts/{aid}/discounts/available_for_receipt/claims Get all claims, limited by parameters. The result will match all parameters with `AND` scopes: - admin:discounts - read:discounts - read:discounts:/available_for_receipt # Post receipt for discount Source: https://docs.dintero.com/api-reference/use-discounts/aid_discounts_available_for_receipt_post /mintlify-docs/openapi/spec-discounts.yaml post /accounts/{aid}/discounts/available_for_receipt Find discounts available for the receipt ### Active discounts - `customer_id` will be used to find active discounts for the purchase. - `customer.token` will be used to resolve `customer_id` if no `customer_id` is provided. - No discounts will be given if the token does not resolve to any customer_id. - A receipt with no `customer_id` and no `customer.token` will only be applicable for active discounts given to **`/`** ([see](/discounts-api/rules-customers/aid_discounts_did_customers_post)) ### Requirement of the receipt - all items must have `eligible_for_discount` set to enable for discount - all items must have a positive `gross_amount` to qualify for discount - a `net` base discount reward requires the receipt to include existing discounts as discount_lines (on item) in order to calculate net A receipt that qualified for discount will have the `is_change` property set to true. Any items that has received a discount will be flagged by `is_change` and have one or more new entries to its discount_lines. The receipt `discounts` list will be populated with all discounts the receipt is qualified to receive scopes: - admin:discounts - write:discounts - write:discounts:/available_for_receipt # Claim discounts Source: https://docs.dintero.com/api-reference/use-discounts/aid_discounts_available_for_receipt_post_claim /mintlify-docs/openapi/spec-discounts.yaml post /accounts/{aid}/discounts/available_for_receipt/claims Claim discount rewards, checks will be done to ensure that all discount limitation are uphold Note, only the following discount limitation will affect the success of a claim - discount_reward_usage - discount_repeat_usage scopes: - admin:discounts - write:discounts - write:discounts:/available_for_receipt # Post event Source: https://docs.dintero.com/api-reference/use-discounts/aid_discounts_events_post /mintlify-docs/openapi/spec-discounts.yaml post /accounts/{aid}/discounts/events Send an Event to the service. - rules automations will receive the event and give its discount to the customer found in the event - Token received will be stored to support resolving customer from token when handling discounts available for receipt scopes: - admin:discounts - write:discounts - write:discounts:/events # Change customer_id Source: https://docs.dintero.com/api-reference/users/aid_customers_cid_change_customer_id_post /mintlify-docs/openapi/spec-customers.yaml post /accounts/{aid}/customers/users/{customer_id}/change_customer_id Update customer_id for an customer **warning**: Any external resources "owned" by the user, i.e receipts, discounts etc. will not be updated with the new customer_id. A new metadata property `dintero_change_customer_id_{timestamp}.{hash}` will be added everytime the customer_id is changed Following data will be included in the metadata property - created_at - created_by - old - new scopes: - admin:customers - admin:accounts # Delete customer Source: https://docs.dintero.com/api-reference/users/aid_customers_cid_delete /mintlify-docs/openapi/spec-customers.yaml delete /accounts/{aid}/customers/users/{customer_id} Delete single customer scopes: - admin:customers - write:customers - user:customers # Customer details Source: https://docs.dintero.com/api-reference/users/aid_customers_cid_get /mintlify-docs/openapi/spec-customers.yaml get /accounts/{aid}/customers/users/{customer_id} Customer details scopes: - admin:customers - read:customers - user:customers - user:customers:/customer/details # Update Customer Source: https://docs.dintero.com/api-reference/users/aid_customers_cid_put /mintlify-docs/openapi/spec-customers.yaml put /accounts/{aid}/customers/users/{customer_id} Update customer properties, properties not included in the body will remain unchanged. scopes: - admin:customers - write:customers - user:customers # Customer collection Source: https://docs.dintero.com/api-reference/users/aid_customers_get /mintlify-docs/openapi/spec-customers.yaml get /accounts/{aid}/customers/users Get all customers, limited by parameters. The result will match all parameters with `AND`. Search is done by prefix match, and `+` in phone_number/email must be URL encoded, (+4799999999 => %2B4799999999) Users with type `contact` are by default excluded from the result, use `type=contact` or `type=any` to include contact users The response from a request that match contact users will include the users that are linked from the contact scopes: - admin:customers - read:customers # User exist Source: https://docs.dintero.com/api-reference/users/aid_customers_head /mintlify-docs/openapi/spec-customers.yaml head /accounts/{aid}/customers/users Check if there is users that match the parameters. The result will match all parameters with `AND`. This endpoint must be enabled from [PUT /customers/settings](/customers-api/settings/aid_customers_atributes_put) scopes: - admin:customers - read:customers - public:customers # Create new Customer Source: https://docs.dintero.com/api-reference/users/aid_customers_post /mintlify-docs/openapi/spec-customers.yaml post /accounts/{aid}/customers/users Create a new customer, `customer_id`, `email` and `phone_number` must be unique if specified. scopes: - admin:customers - write:customers - create:customers:/users # List seller balances Source: https://docs.dintero.com/api-reference/v2-config-payout-destinations/v2_aid_payout_destination_balance_get /mintlify-docs/openapi/spec-payments-v2.yaml get /v2/accounts/{aid}/payout/payout-destinations/{payout_destination_id}/balances Get seller balance per currency # List seller transfers Source: https://docs.dintero.com/api-reference/v2-config-payout-destinations/v2_aid_payout_destination_transfers_get /mintlify-docs/openapi/spec-payments-v2.yaml get /v2/accounts/{aid}/payout/payout-destinations/{payout_destination_id}/transfers Get list of transfers for a seller # Handling payment Source: https://docs.dintero.com/docs/checkout/after-payment Handle Dintero Checkout transactions after payment with return_url and callback_url, transaction statuses, and idempotent post-payment processing. When the payment is completed, a **transaction** is created with info about the payment method used, card details, and success status. `order.shipping_option` from the session will be moved to an item in the transaction. The session will contain a `transaction_id` referencing the transaction. There will only be one transaction for any one session. ## Transaction statuses The possible states the transaction can be in after completion are: * **AUTHORIZED** - successful payment * **ON_HOLD** - further controls are necessary, will change to **AUTHORIZED** or **FAILED** later * **CAPTURED** - auto-capture is turned on, and the money was withdrawn from the customer's account. auto-capture could have been turned on in the payment profile, or at the payment provider. Might also be captured if someone was really, really fast at capturing it manually. * **FAILED** - payment failed * **DECLINED** - customer declined the payment while it was processing ## Getting notified about the transaction status The website should implement `url.return_url` and `url.callback_url`. The integration must handle parallel execution of both `return_url` and `callback_url` handlers. `return_url` can be used for marking the order as paid and showing a success page to the customer, but we can never guarantee that the customer will actually be redirected there. The customer might have connection issues, navigate to another website before being redirected, or turn off their device. ### callback_url The callback_url will be invoked when a payment is complete and the transaction has been authorized. Unlike return_url the callback_url is **machine-to-machine** which means delivery is guaranteed. The `callback_url` must be publicly available and be a HTTPS URL. Once the payment is complete the callback_url is invoked as a **`GET`** request to notify the system that the payment has been approved. It's possible to customize the behaviour of the callback by setting different query parameters on the callback_url. For example, if you want to receive callbacks on errors, set the query parameter `report_error=true`. #### Failed payment attempts Dintero does not send a callback for each failed payment attempt. If a card is declined, for example for insufficient funds, the customer can try again in the same session, so Dintero treats the attempt as a temporary failure. Without `report_error=true`, Dintero only calls the callback_url for transactions with the status `AUTHORIZED`, `CAPTURED` or `ON_HOLD`, including the follow-up callback when an `ON_HOLD` transaction changes status. Cancelled, declined and failed payments send no callback, so you only learn about them from the `error` on the return_url or by checking the session. Set `report_error=true` to get a callback for these outcomes too. With `report_error=true` set, Dintero calls the callback_url once when the payment ends without an authorized transaction. The `error` query parameter tells you why: | error | Description | | - | - | | `cancelled` | The customer cancelled the payment, or the transaction was declined | | `authorization` | A transaction was created, but the customer did not complete the authorization | | `failed` | The transaction failed, or an error occurred during transaction processing | If no transaction was created, for example when the customer cancels, the error callback has no `transaction_id`. See `url.callback_url` in [the API docs](/api-reference/session/checkout_session_profile_post) for more customization options. A successful delivery to an HTTPS callback_url sometimes requires more than one attempt. This can be the case, for example, if the server hosting the callback_url is down for maintenance or is experiencing heavy traffic. Dintero attempts a retry only after a failed delivery attempt, the following situations are considered as failed delivery * HTTP status code 100 to 101 and 500 to 599 (inclusive) (HTTP status code 400 to 499 is considered as permanent failure) * A request timeout (10 seconds) * Any connection error such as connection timeout, bad certificate, etc Failed deliveries will be retried 20 times. > The service receiving the request for the `callback_url` **must verify** the > request by checking the status of the transaction_id before the order payment > status is updated. The following query parameters will be included in the callback request | query | type | required | | - | - | - | | transaction_id | string | true | | session_id | string | true | | merchant_reference | string | true | | time | string | true | ### return_url Once payment is complete or canceled the user is redirected to the return_url via a **`GET`** request. The following query parameters will be included in the return_url request | query | type | required | | - | - | - | | transaction_id | string | false | | error | string | false | | merchant_reference | string | false | * If a transaction was completed successfully, a transaction_id will be appended to the return_url * If the user decides to cancel the payment, an error with value `cancelled` will be appended to the return_url * See \[the full list of return_url errors] > Building logic relying on the order of return_url is not recommended. > It is not guaranteed that they will be invoked, since the user might interfere with it. > There could be various reasons for the urls not to be invoked like computer > closing the browser, entering a new page, etc. See more details about callback_url and return_url in [the API docs](/api-reference/session/checkout_session_profile_post). #### return_url for non website users If you do not have a custom return_url you can use the default return_url used by our own Digital Terminal: ```text theme={null} https://checkout.dintero.com/result/ ``` ## Redirect / callback with transaction status ON_HOLD A transaction can in some cases end up in an `ON_HOLD` status when the redirect/callback is done. Transactions with this status require additional async controls before the transaction can be **AUTHORIZED**. Transactions with status `ON_HOLD` should be handled as payment pending and you can expect an additional callback when the transaction changes status from `ON_HOLD`. > It is recommended that callback is supported to receive the additional > update when the transaction changes status from `ON_HOLD` to **AUTHORIZED** > or **FAILED**. > The alternative is to poll the transaction every hour until it changes > status from `ON_HOLD`. #### Errors | error | Description | | - | - | | cancelled | Customer cancelled the checkout payment | | authorization | Customer failed to authorize the payment | | failed | The transaction has been rejected by us, or an error has occurred during transaction processing | | capture | The transaction capture operation failed during auto-capture | ## Auto refunds When paying with Vipps or Swish, if the customer has already gotten the payment in the app, if the session is cancelled there is a small window where the customer can still complete the payment in the app. If the session was configured with auto-capture and the customer completed the payment after the session was cancelled, Dintero will automatically issue a refund. Auto refunds can be identified by the `created_by` field on the refund event being set to `dintero/auto-refund`. ## Updating transaction with merchant_reference_2 If the order has any new references that needs to be available on the transaction, it can be updated. To do this, see [here](/api-reference/transactions/transactions_id_put). # Age verification Source: https://docs.dintero.com/docs/checkout/age-verification Require customers to prove they meet a minimum age before completing checkout, using BankID or MitID. Age verification stops checkout until the customer has proven they are old enough. It applies to the whole session, not a single payment method. The customer authenticates with BankID or MitID. This is currently only available for customers in Norway, Sweden, and Denmark. In hosted checkout they are asked to verify before they can choose a payment method. If you drive checkout yourself, follow the `complete-age-verification` operation. ## How it works ```mermaid theme={null} sequenceDiagram participant Customer participant Dintero participant IdP Customer->>Dintero: Opens checkout Dintero->>IdP: Redirect to BankID / MitID IdP-->>Dintero: Identity + birthdate alt Age meets requirement Note over Dintero: AGE_VERIFICATION_COMPLETED Dintero-->>Customer: Checkout with payment methods else Too young, cancelled, or failed Dintero-->>Customer: Redirect with error end ``` 1. Enable `age_verification` on the session (or session profile). 2. The customer opens checkout and verifies their age before they can pay. 3. They authenticate with BankID or MitID. 4. The session records `AGE_VERIFICATION_COMPLETED` with `verified_identity.age_over`. 5. Checkout continues as usual. The transaction copies that identity unless the payment type already has one. ## Step-by-step implementation ### 1. Configure the session Set `age_verification` on `POST /v1/sessions`: ```http theme={null} POST /v1/sessions Authorization: Bearer Content-Type: application/json { "url": { "return_url": "https://example.com/accept", "callback_url": "https://example.com/callback" }, "order": { "amount": 29900, "currency": "NOK", "vat_amount": 5980, "merchant_reference": "order-123", "items": [ { "amount": 29900, "quantity": 1, "line_id": "1", "description": "Age-restricted item", "vat": 25, "id": "item-1" } ] }, "configuration": { "age_verification": { "enabled": true, "minimum_age_required": 18 } } } ``` ### 2. Customer completes verification **Hosted checkout.** Nothing extra to build. Checkout asks the customer to verify their age before they can pick a payment method, then sends them to BankID or MitID and brings them back to the session. ![Age verification in checkout](https://mintcdn.com/dintero-c3a7bfec/XcvJgiNLXtm0IKyL/docs/assets/checkout/checkout_age_verification.png?fit=max\&auto=format\&n=XcvJgiNLXtm0IKyL\&q=85\&s=cc6bc786a4f7d977c4c7580ed146b2bf) **Custom or API checkout.** If you start a payment while verification is still required, the response contains only this operation: ```json theme={null} { "operations": [ { "rel": "complete-age-verification", "method": "GET", "content_type": "text/html", "href": "https://checkout.dintero.com/v1/view/{session_id}/age-verification" } ] } ``` Send the customer to `href`. After they pass, they come back with `sid`. Retry the payment. The operation is gone once `age_over` meets `minimum_age_required`. > [!NOTE] > > Starting verification again reuses the pending identity-provider URL for a few minutes, so the customer is not sent through BankID or MitID twice. ### 3. Receive the session event A successful verification appends `AGE_VERIFICATION_COMPLETED`. The national identity number is never included. ```json theme={null} { "name": "AGE_VERIFICATION_COMPLETED", "details": { "verified_identity": { "type": "dintero-idp", "age_over": 21, "acr": "nobankid-oidc", "national_country": "NO", "auth_time": "2026-09-02T10:00:00Z" } } } ``` When the transaction is created, that `verified_identity` is copied onto it. ## Configuration options | Option | Type | Required | Description | | - | - | - | - | | `enabled` | Boolean | Yes | Turn age verification on for the session | | `minimum_age_required` | Integer | Yes | Minimum age, for example `18` | The identity provider country is taken from, in order: 1. `order.billing_address.country` 2. `order.shipping_address.country` 3. `configuration.countries.preferred_country` | Country | Identity provider | | - | - | | `NO` | BankID | | `SE` | BankID | | `DK` | MitID | If the country is missing or unsupported, the customer picks from the providers above. ## Verified Age The exact age is not stored. `age_over` is the highest of `21`, `18`, `16`, and `15` that the customer meets, and that is still at least `minimum_age_required`. | Actual age | `minimum_age_required` | `age_over` | | - | - | - | | 30 | 18 | 21 | | 19 | 18 | 18 | | 17 | 18 | Redirect, no event | ## Failures and redirects If verification fails or is cancelled, the customer is sent back to the session URL with `error` and `merchant_reference` (when available). Embed context (`ui`, `sdk`) is kept. | `error` | Meaning | | - | - | | `age-requirement-not-met` | Authenticated, but too young. No `AGE_VERIFICATION_COMPLETED` event. | | `cancel` | The customer cancelled at the identity provider. | | `authorization-failed` | Authorization with the identity provider failed. | | `failed` | Verification could not be completed, for example if age could not be determined. | ## Direct Pay `POST /v1/sessions/{session_id}/pay` is blocked until verification completes: ```json theme={null} { "success": false, "error": "age-verification-required", "redirect_url": "https://checkout.dintero.com/v1/view/{session_id}/age-verification", "actions": [ { "source": "DINTERO", "code": "age-verification-required", "type": "error" } ] } ``` Send the customer to `redirect_url`, then retry the pay request. > [!NOTE] > > The customer has to complete verification themselves. Merchant-initiated or headless pay can still use age verification if you send the customer to `redirect_url` first, but it may not fit flows where no customer is present. ## Identity verification If a payment type on the session also needs identity verification, age verification collects that identity at the same time. The customer is not asked to authenticate twice. The national identity number is never exposed on the session event or on the transaction in API responses. If the payment type later verifies identity itself, that identity is kept on the transaction. ## See also * [Create a session](/docs/checkout/create-session): enable `age_verification` when you create the session * [Show checkout](/docs/checkout/display-checkout): hosted checkout handles the redirect for you * [Handling payment](/docs/checkout/after-payment): the transaction after checkout completes # Dintero Hosted Checkout Source: https://docs.dintero.com/docs/checkout/apple-pay/apple-pay-hosted-checkout Enable Apple Pay in Dintero Hosted Checkout, including domain verification for embedded checkout and using pop-out or redirect flows on unverified domains. The easiest way to use Apple Pay is by using the Dintero checkout solution, where we handle the entire payment flow for you. If you are already using Dintero checkout, you just need to enable Apple Pay. Note that if you use the [embedded checkout](/docs/checkout/embedVredirect#checkout-embedded) flow you need to verify your own domain before you can use Apple Pay. If you are not able to verify the domain you can still accept payments via Apple Pay by using the [redirect](/docs/checkout/embedVredirect#checkout-redirect) payment flows. ### Getting started To use Apple Pay as a payment method, you must comply with Apple Pay's Acceptable Use Guidelines and accept their terms of service. You also need to set up a Dintero account. #### Enable Apple Pay on your Dintero account During your onboarding you will be able to select Apple Pay as a payment method. If it's not enabled, you can go to settings and payment methods. From there, you can enable Apple Pay as a payment method for your account. If you use payment profiles, ensure that Apple Pay is added to the relevant profiles. #### Authentication methods Apple Pay transactions are authenticated on the user's device using biometric authentication (Face ID, Touch ID) or a device passcode. This authentication is a core security feature of Apple Pay and provides a high level of security. Dintero's hosted checkout solution handles this authentication process seamlessly on behalf of the merchant. Since Apple Pay transactions are already authenticated on the device, they benefit from "liability shift," which means the merchant is protected from fraudulent chargebacks. This security feature eliminates the need for an additional 3-D Secure authentication step, creating a faster and more streamlined checkout experience. Dintero's hosted checkout handles this process automatically. #### Embedding the checkout on your own domain > [!NOTE] > > Embedding Apple Pay is only supported with `dintero_psp.applepay`. If you are using Apple Pay via Worldline (`bambora.applepay` in the API), embedding is not supported. However, *pop-out* or *redirect* flows are available. Domain verification is only needed if you use the [embedded the checkout on your own website](/docs/checkout/embedVredirect#checkout-embedded). If you use *pop-out* or *redirect* then domain verification is not required. To verify that a website is authorized to process Apple Pay on the web for a specific merchant, Apple requires a domain association file to be hosted on the merchant's domain. This file is placed in the standardized .well-known directory. Use [this file](https://checkout.dintero.com/.well-known/apple-developer-merchantid-domain-association) for Apple Pay domain verification. * Serve the file from `https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association` * The recommended MIME type is `text/plain; charset=utf-8`. > Note: The file has no extension (e.g., .txt or .json), which can sometimes cause issues with certain web server configurations. If your server struggles to serve a file without an extension, you may need to add a specific MIME type or a URL rewrite rule. When the file is served from your domain contact [integration@dintero.com](mailto:integration@dintero.com) and we will update your account with support for your custom domain. > [!NOTE] > > Apple Pay on embedded checkout requires [`@dintero/checkout-web-sdk`](https://github.com/Dintero/Dintero.Checkout.Web.SDK) version `0.9.0` or later (latest recommended). Earlier versions will not load Apple Pay even on a verified domain. > > If your checkout page is itself embedded inside another iframe, also watch for `sdk_not_top_level=true` on the checkout iframe `src` - Apple Pay is suppressed in that case even with an up-to-date SDK. #### One click Apple Pay in Checkout Express For [Checkout Express sessions](/docs/checkout/express) we support a one click Apple Pay checkout flow where the customer can pay by clicking an Apple Pay button that is shown above the customer data form. When the customer clicks this button the session is updated with customer details from Apple Pay and the customer selects a shipping option in the Apple Pay UI. Since Apple Pay's express features behaves a bit differently from the default Checkout Express flow this requires an opt in property in the session configuration, the `allow_express_wallet_payment` must be set to `true`. Apple Pay can still be used for payment in Express Checkout when this flag is not set. Apple Pay will then be shown next to the other payment options after the customer has entered their address details manually. ##### *One click* Apple Pay requirements for your shipping address callback endpoint Your endpoint must support returning shipping options when the `session.order.shipping_address` in the request body from Dintero’s systems contains only `country` and `postal_code`. See also full documentation for [the shipping address callback endpoint](/docs/checkout/shipping-address-callback). ### Testing #### Sandbox environment You can test Apple Pay in a sandbox environment to simulate payments without charging any real cards. Dintero provides a test mode that allows you to trigger a test Apple Pay payment sheet, so you can confirm that the integration works as expected. #### Production testing When you are ready to test in production, you can enable Apple Pay for your production environment. These payments will actually charge the card, so you should test with a small amount and be prepared to cancel or refund the transaction after testing. To avoid exposing Apple Pay to customers while testing, you can use [a payment profile](/docs/checkout/payment-profiles) that includes Apple Pay, and only use this profile for your testing purposes. ### Further reading * [The official Apple Pay documentation for domain verification](https://developer.apple.com/documentation/applepaywebmerchantregistrationapi/preparing-merchant-domains-for-verification). # Native app integration Source: https://docs.dintero.com/docs/checkout/apple-pay/apple-pay-native-app Integrate Apple Pay in your iOS app using PassKit and Dintero PSP for full control over the in-app payment sheet and merchant onboarding. Native app integration provides you with complete control over the Apple Pay user experience within your iOS application. While Dintero handles the payment processing, you implement the Apple Pay user interface directly using Apple's frameworks (like PassKit), providing a seamless and highly customized experience for your customers. > [!NOTE] > > Native app integration with Apple Pay is supported only via `dintero_psp.applepay`. If you are using Worldline (`bambora.applepay` in the API), native app integration is not available. ### Prerequisites #### Apple Pay merchant onboarding Before you can implement Apple Pay in your app, you must complete Apple's merchant onboarding process through your Apple Developer Account. This process involves several key steps: * Create a Merchant Identifier: This is a unique identifier that registers your business with Apple as a merchant capable of accepting payments. A single merchant identifier can be used for multiple apps and websites. * Create a Payment Processing Certificate: This certificate is associated with your merchant ID and is used to encrypt payment data. Contact [integration@dintero.com](mailto:integration@dintero.com) and request a Certificate Signing Request (CSR) from Dintero and use the CSR to create this certificate with Apple. After the certificate has been created you have to download the certificate and get in touch with [integration@dintero.com](mailto:integration@dintero.com) for instructions on how to send us your certificate. * Enable Apple Pay in Xcode: You need to enable the Apple Pay capability within your Xcode project settings and link it to the merchant identifier you created. Note: This process requires an active Apple Developer Program account and can take some time, so it's best to plan accordingly. > [!NOTE] > > For Apple Pay integration, you must create and use **two separate merchant identifiers** and **two separate Apple Pay Payment Processing Certificates**: one set for your test (sandbox) environment and one set for your production environment. Each certificate must be created using the corresponding merchant identifier and environment selection in the Apple Developer portal. #### Enable Apple Pay on your Dintero account During your onboarding you will be able to select Apple Pay as a payment method. If it's not enabled, you can go to settings and payment methods. From there, you can enable Apple Pay as a payment method for your account. If you use payment profiles, ensure that Apple Pay is added to the relevant profiles. ### Integration with Dintero The native payment flow with Apple Pay and Dintero is a collaborative process between your app and Dintero's API. The general flow is as follows: 1. The user taps the Apple Pay button in your app to begin the checkout process. 2. Your app requests a session from Dintero's API. 3. Your app fetches payment operations for the session. 4. Your app uses the PassKit framework to present the Apple Pay payment sheet to the user. 5. After the user authenticates the payment with Face ID, Touch ID, or their passcode, Apple Pay returns an encrypted PKPaymentToken. 6. Your app sends the encrypted payment token to Dintero using the endpoint returned in step 3. 7. Your app initiates the checkout Payment using the `transaction_id` returned in step 6 and Dintero creates an authorized transaction ```mermaid theme={null} sequenceDiagram actor C as Customer participant A as Your app participant AP as Apple Pay participant DC as Dintero Checkout participant DPS as Dintero PSP Service C->>A: 1. User starts payment (taps Apple Pay button) A->>DC: 2. Request Session (to Dintero API) DC-->>A: Session ID / Response A->>DC: 3. Fetch Payment operation for session DC-->>A: Payment operations for apple pay A->>AP: 4. Request Payment Data (Presents Apple Pay sheet via PassKit) AP-->>C: Presents Apple Pay Sheet C->>AP: Authenticates payment (Face ID/Touch ID) AP-->>A: 5. Returns Encrypted Payment Data (PKPaymentToken) Note over A: Token is encrypted A->>DPS: 6. Post Payment Data to Dintero PSP DPS->>DPS: Decrypts token and communicates with Card Network DPS-->>A: PSP result A->>DC: 7. Initiating checkout payment with PSP result DC-->>A: Session Result Note over A: Update UI/Complete checkout ``` This integration gives you full control over the user experience while leveraging Dintero's secure and reliable payment processing backend. > Note that only the Visa and Mastercard payment networks are supported. #### Creating an Apple Pay session (step 2) Example session request body, note that the return_url must match the app url namespace and that `initial_recipient=merchant` must be set if the link in the session payment response should be followed. ```json theme={null} { "url": { "return_url": "yourapp://redirect?initial_recipient=merchant", "callback_url": "https://your-backend-callback-handler.com/endpoint" }, "order": { "amount": 20100, "currency": "NOK", "merchant_reference": "", "items": [ { "id": "", "line_id": "", "description": "Item to be paid for", "amount": 20100, "quantity": 1, "vat_amount": 4020, "vat": 25 } ] }, "configuration": { "channel": "in_app", "dintero_psp": { "applepay": { "enabled": true } } }, "expires_at": "2099-12-31T23:23:59.999Z" } ``` #### Fetching payment operations for the session (step 3) The payment operations describe how to post payment data from Apple Pay to Dintero. For a native app integration only the operation with `rel` set to `submit-dintero-psp-applepay` is used. Example request (note, there is no body or content type in this POST request): ```http theme={null} POST https://checkout.dintero.com/v1/view/{session_id}/payments/dintero_psp.applepay ``` Example response body: ```json theme={null} { "operations": [ { "href": "https://payments.psp.dintero.com/apple-pay/v1/{account_id}/payments/{payment_id}/transactions?access_token={access_token}", "method": "POST", "rel": "submit-dintero-psp-applepay", "content_type": "application/json", "supported_networks": [ "VISA", "MASTERCARD" ], "merchant_country": "NO" }, { "href": "https://payments.psp.dintero.com/apple-pay/v1/{account_id}/payments/{payment_id}/validate-merchant?access_token={access_token}", "method": "POST", "rel": "validate-dintero-psp-applepay-merchant", "content_type": "application/json" } ] } ``` #### Posting payment data from Apple Pay (step 6) Post the encrypted payment data from Apple Pay to Dintero. For this you use the `submit-dintero-psp-applepay` payment operation. Extract the `access_token` query parameter from the operation `href` and post the payment data. Please remove the `access_token` query param from the URL before posting payment data. Ensure you send the `payment_data` as a JSON string. ##### Transforming the Apple Pay payment token The `PKPaymentToken` from Apple Pay cannot be sent directly. It must be transformed into the following JSON structure before being stringified as `payment_data`: ```json theme={null} { "payment": { "token": { "paymentData": { "data": "", "signature": "", "header": { "publicKeyHash": "", "ephemeralPublicKey": "", "transactionId": "" }, "version": "" // eg. "EC_v1" }, "paymentMethod": { "displayName": // "Visa 1234", "network": "token.paymentMethod.network?.rawValue" // "Visa", "type": "token.paymentMethod.type.stringValue" // "debit" }, "transactionIdentifier": "" } } } ``` The fields map from `PKPayment` as follows: | JSON field | Source | | - | - | | `paymentData` | Decode `PKPaymentToken.paymentData` (raw `Data`) as JSON | | `paymentMethod.displayName` | `PKPaymentToken.paymentMethod.displayName` | | `paymentMethod.network` | `PKPaymentToken.paymentMethod.network.rawValue` (e.g. `"Visa"`, `"MasterCard"`) | | `paymentMethod.type` | `PKPaymentToken.paymentMethod.type` as string (e.g. `"debit"`, `"credit"`) | | `transactionIdentifier` | `PKPaymentToken.transactionIdentifier` | See the [reference implementation](https://github.com/Dintero/dintero-ios-native-example) for a complete Swift example of this transformation. Example request ```http theme={null} POST https://payments.psp.dintero.com/apple-pay/v1/{account_id}/payments/{payment_id}/transactions Authorization: {access_token} Content-Type: application/json Body: { "payment_data": "{JSON stringified object with the structure described above}", "reference": "{unique id}" } ``` Example response body ```json theme={null} { "payment_id": "{payment_id}", "transaction_id": "{transaction_id}", "type": "APPLE_PAY_AUTHENTICATION" } ``` #### Initiating checkout payment (step 7) Initiating the checkout payment using the `transaction_id` returned when posting the payment data. ```http theme={null} POST https://api.dintero.com/v1/accounts/{account_id}/payments/sessions/{session_id}/pay Content-Type: application/json Body: { "payment_product_type": "dintero_psp.applepay", "psp_transaction_id": "{transaction_id}" } ``` After posting to the initiate checkout payment endpoint the session is completed and has created an authorized transaction. The payment response will contain a `return_url` but there is no need to follow or call it. ### Best practices Make sure you follow the following best practices. * Never log or store Apple Pay tokens * Implement proper error handling to avoid exposing sensitive information * Validate all payment responses on your server ### Example application See [https://github.com/Dintero/dintero-ios-native-example](https://github.com/Dintero/dintero-ios-native-example) for an example application on how to accept Apple Pay payments. ### Further reading * [Apple Pay Developer Documentation](https://developer.apple.com/documentation/PassKit/apple-pay) * [Apple Pay Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/apple-pay) * [Apple Pay Marketing Guidelines](https://developer.apple.com/apple-pay/marketing/) * [Apple Pay Merchant Integration Guide ](https://developer.apple.com/apple-pay/Apple-Pay-Merchant-Integration-Guide.pdf) # Overview Source: https://docs.dintero.com/docs/checkout/apple-pay/apple-pay-overview Compare Apple Pay integration options with Dintero, including hosted checkout, embedded checkout with domain verification, and native iOS app integration. [Hosted Checkout]: /docs/checkout/apple-pay/apple-pay-hosted-checkout [Hosted Checkout Domain Verification]: /docs/checkout/apple-pay/apple-pay-hosted-checkout#embedding-the-checkout-on-your-own-domain [Native App Integration]: /docs/checkout/apple-pay/apple-pay-native-app Apple Pay™ is a digital wallet and mobile payment service that enables users to make secure and contactless payments with their Apple devices, such as iPhones, Apple Watches, and iPads. It tokenizes a user's card information, providing a secure and private way to pay for goods and services in stores, within apps, and on the web. ### Integration options with Dintero There are primarily two ways to support Apple Pay in your payment flow: hosted checkout or native app integration. #### 1. Hosted checkout If you are using our hosted checkout solution, you can add Apple Pay without any direct integration with Apple Pay's APIs. Simply enable Apple Pay in your Dintero settings, and we will handle the rest, including the payment sheet display and transaction processing. If you want to embed the checkout on your own domain the domain needs to be verified. See the [Hosted Checkout Domain Verification] instructions. #### 2. Native app integration For merchants who require a more customized and integrated payment experience, such as in a native mobile or web application, you can integrate with Apple Pay yourself. This gives you full control over the user interface and payment flow, while still leveraging Dintero as your payment gateway. ### Apple Pay feature support by PSP provider Dintero supports Apple Pay payments through both our own PSP and via Worldline. The table below shows which integration types are supported by each provider. | PSP | Native | Hosted | Hosted Embedded | | - | :-: | :-: | :-: | | Dintero | ✅ | ✅ | ✅ | | Worldline | ❌ | ✅ | ❌ | ### Liability Apple Pay processes payments through the customer's underlying card (credit, debit, or prepaid). This means: * **Chargeback risk**: Transactions are subject to card network chargeback rules. Customers can dispute charges through their card issuer (e.g., fraud disputes, items not received), following the same process and liability rules as regular card payments. * **Strong authentication**: Payments are authenticated using device biometrics (Face ID, Touch ID) or device passcode. This satisfies Strong Customer Authentication (SCA) requirements and reduces the risk of fraudulent use compared to manual card entry. * **Funds guarantee**: Apple Pay transactions go through a standard card authorization flow. An `AUTHORIZED` transaction means funds have been reserved at the card network level, and a `CAPTURED` transaction means funds are on their way to settlement. * **ECI**: Merchants can inspect the `card.eci` field on an authorized transaction before capturing to determine the authentication level and resulting liability. A value of `05` (Visa) or `02` (Mastercard) indicates full SCA with liability shift to the issuer. `06`/`01` indicates authentication was attempted. `07`/`00` indicates no authentication was performed and the merchant bears fraud liability. ### Next steps Explore Native App Integration for native iOS and web implementation. * Learn about [Hosted Checkout] for a simple, managed integration * Explore [Native App Integration] for native iOS implementation # Create an API client Source: https://docs.dintero.com/docs/checkout/checkout-client Step-by-step guide for creating a Dintero API client in Backoffice and saving the client_id and client_secret credentials safely. To start using the Dintero Checkout on your website, you need to create an API client through the **Dintero Backoffice**. ### Step by step-guide First, log into **[Backoffice](https://backoffice.dintero.com)**, then follow this interactive slide-show: 1. Click on **settings**. 2. Under API & Integrations click on **API clients**. 3. Click on **Create new API client**. 4. Click on **Checkout client**. 5. Write the **URL** of your website. 6. Click on **Create new API client**. 7. Remember to **Save the credentials**, the **Client Secret** can not be shown again. 8. Click **OK**. 9. The Client is now **Created**. [Dintero Backoffice](https://demo.arcade.software/ZYZn1cDpEwxbB007nUGZ?embed) #### Using our plugin If you’re using our plugin, most of the technical details below are handled automatically. You can skip the following sections unless you’re customizing the integration or coding it yourself. ## Authentication Use your `client_id` and `client_secret` to get an access token from the auth endpoint. ```bash theme={null} curl https://api.dintero.com/v1/accounts/T12345678/auth/token \ -u "CLIENT_ID:CLIENT_SECRET" \ -H 'Content-Type: application/json' \ -d '{ "grant_type": "client_credentials", "audience": "https://api.dintero.com/v1/accounts/T12345678" }' ``` The response contains an `access_token` and its lifetime in seconds: ```json theme={null} { "access_token": "eyJhbGci...t7P4", "token_type": "Bearer", "expires_in": 14400 } ``` Use the token as a Bearer header on all subsequent requests: ```http theme={null} Authorization: Bearer {access_token} ``` > [!TIP] > > Cache the token and only request a new one when it is about to expire, not on every request. # Discount codes in Express Checkout Source: https://docs.dintero.com/docs/checkout/checkout-express-discount-code Enable discount codes in Dintero Express Checkout by implementing the Discount Code Update callback and configuring the express discount_codes object. To enable discount code in Dintero Express Checkout, implement the "Discount Code Update" callback endpoint: * [Discount Code Update endpoint](/api-reference/example-session-callbacks/example_discount_codes_callback_url) and create session where `express_discount_codes` is enabled and express `discount_codes` is configured with a callback_url ```json theme={null} { "profile_id": "default", "url": { "return_url": "https://merchant/return" }, "order": { "items": [ { "amount": 2009990, "vat_amount": 401998, "vat": 25, "quantity": 1, "line_id": "l1" } ], "amount": 2009990, "vat_amount": 401998, "currency": "NOK", "merchant_reference": "reference" }, "express": { "shipping_options": [], "discount_codes": { "callback_url": "http://merchant/discount_code_callback_url", "max_count": 3 } }, "configuration": { "discounts": { "express_discount_codes": { "enabled": true } } } } ``` # Test data Source: https://docs.dintero.com/docs/checkout/checkout-testdata Overview of Dintero Checkout sandbox test data, including PSP cards, alternative payment methods, bank accounts, and split-payment auto-approval values. Use the sandbox to verify your integration without moving real money. Try out the [Dintero Checkout Demo](https://checkout.demo.dintero.com/) or pick a payment method below. ## Card payments > [card] [Dintero PSP cards](/docs/checkout/testdata/dintero-psp/checkout-dintero-cards-testdata) > > 3D-Secure flows, declined card scenarios, and simulated authorization response codes. > [card] [Swedbank Pay cards](/docs/checkout/testdata/other/checkout-swedbank-testdata) > > Visa, Mastercard, tokens, and magic amounts for Swedbank Pay. > [card] [Worldline (Bambora) cards](/docs/checkout/testdata/other/checkout-bambora-testdata) > > Visa and Mastercard for Worldline (Bambora). ## Wallets > [card] [Vipps](/docs/checkout/testdata/other/checkout-vipps-testdata) > > Norwegian wallet test data. > [card] [Swish](/docs/checkout/testdata/other/checkout-swish-testdata) > > Swedish wallet test data. > [card] [MobilePay](/docs/checkout/testdata/other/checkout-mobilepay-testdata) > > Danish wallet test data. ## Invoice & BNPL > [card] [Klarna](/docs/checkout/testdata/other/checkout-klarna-testdata) > > B2C and B2B flows for Norway including dispute scenarios. > [card] [Billie](/docs/checkout/testdata/other/checkout-billie-testdata) > > B2B test companies in Sweden. > [card] [Kravia](/docs/checkout/testdata/other/checkout-kravia-testdata) > > Invoice payment outcome aliases. > [card] [Two](/docs/checkout/testdata/other/checkout-two-testdata) > > B2B companies, credit limits, and verification thresholds in Norway and Sweden. > [card] [Walley](/docs/checkout/testdata/other/checkout-walley-testdata) > > B2C and B2B test persons for Norway, Sweden, Denmark, and Finland. > [card] [Instabank](/docs/checkout/testdata/other/checkout-instabank-testdata) > > SSNs and BankID credentials for Instabank Finance. ## Other > [card] [Gift cards](/docs/checkout/testdata/other/checkout-giftcards-testdata) > > Test gift card numbers and PINs. > [card] [Discount codes](/docs/checkout/testdata/other/checkout-discount-codes-testdata) > > Test discount codes. ## Split payments See [Testing split payouts](/docs/checkout/split-payment/testing-split-payments) for a walkthrough on testing payout destinations and split payments. > [card] [Test bank accounts](/docs/checkout/testdata/approvals/bank-accounts) > > Bank account numbers for verifying payout destination approvals. > [card] [Auto-approve sellers](/docs/checkout/testdata/approvals/auto-approve) > > Magic `payout_destination_description` values for sandbox approvals. # Custom Checkout Theme Source: https://docs.dintero.com/docs/checkout/checkout-themes Customize the look of Dintero Checkout by setting backdrop, primary color, card radius, and button radius on a session or payment profile. Customize the appearance of your Dintero Checkout. A `theme` configuration can be added either to a session, or to a payment profile. ## Example Custom theme configuration: ```json theme={null} { "backdrop": "#E2DDF8", "primary": "#7863D7", "cardRadius": "6px", "buttonRadius": "6px" } ``` Results in a checkout session that looks like this: ![Themed checkout example](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/custom-checkout-theme.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=546c553975e945c5e9c026472c224f79) ## Colors Supported color formats are * hex: `#ff0000` * rgb: `rgb(255,0,0)` * rgba: `rgba(255,0,0,0.5)` A custom color can be specified for these entities * **backdrop**: Color on backdrop shown in redirect desktop mode * **primary**: Primary color used on pay button and other buttons. ## API documentation For more details see our API specification: * [Create a checkout session](/api-reference/session/checkout_session_profile_post) * [Create a checkout profile](/checkout-api/profiles/admin_session_profile_post) ## Other customizations to the checkout user interface There are also some layout changes can be achieved via query parameters. These are not possible to set in the theme. ### Hiding the items drawer Append the `hide_items=true` query parameter to the checkout session url to hide the items in when the checkout is not embedded (when embedded the items are hidden). ### Hiding the language selector Append the `hide_language=true` query parameter to the checkout session url to hide the language selector. # Checkout Webhook Source: https://docs.dintero.com/docs/checkout/checkout-webhooks Subscribe to Dintero checkout_transaction webhook events to get notified when a transaction is created, captured, refunded, or voided in real time. Create a webhooks subscription on `checkout_transaction` event to receive notification when new transaction is created or updated (captured/refunded or voided) ```json theme={null} POST https://api.dintero.com/v1/accounts/{ACCOUNT_ID}/hooks/subscriptions Authorization: Bearer {access_token} Content-Type: application/json { "config": { "url": "https://example.com/checkout-transaction", "content_type": "application/json" }, "events": [ "checkout_transaction" ] } ``` > [!NOTE] > > See \[Webhooks] for more information about creating webhook subscription ### Checkout transaction event Example of event a subscription can receive ```json theme={null} { "account_id": "P12345678", "event": "checkout_transaction", "event_delivery": "9ebb6d41-dca5-484e-8330-9c9fa96b60ba", "transaction": { "id": "P12345678.465UfBENeLpkBvwmqfTC4k", "session_id": "P12345678.465U8CUzaPVpneu1wt8Wei", "merchant_reference": "ORDER-123", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "merchant_reference_2": "OTHER-ID-123", "status": "AUTHORIZED" } } ``` > [!NOTE] > > See Checkout API to get more details about the transaction object > included in the event > > * \[GET /v1/transaction/\{id}]\[GET /v1/transaction/] ### Handling corrected events An event on a transaction can include a `correction` object when the event's own outcome didn't reflect the transaction's actual state. For example, a capture can time out without a confirmed result even though the transaction was captured. When this happens, Dintero adds a later event whose `correction` object gives the real status and references the event(s) that rectify the transaction: * `correction.status`: The transaction status to use once this event is applied. Use this value to determine the transaction status. * `correction.event_ids`: The IDs of the earlier events that have been added to rectify the transaction. It can be an empty array if no correction events were necessary. See [GET /v1/transaction/\{id}][GET /v1/transaction/{id}] for the full `correction` object. Note that you do not get a separate notification for correction events that are added to rectify the transaction state. > [!WARNING] > > A `success: false` value and an `error` object describe the event operation, > not the transaction's final outcome. Always check `correction.status` first when a > `correction` object is present. See below for an example transaction: ```json theme={null} { "id": "P12345678.465UfBENeLpkBvwmqfTC4k", "status": "CAPTURED", "events": [ ... { "id": "3", "event": "CAPTURE", "success": false, "error": { ... }, "correction": { "status": "AUTHORIZED", "event_ids": [], "remaining_void_amount": 10000, "remaining_refund_amount": 0, "remaining_capture_amount": 10000 }, "transaction_status": "AUTHORIZED" }, { "id": "4", "event": "CAPTURE", "amount": 10000, "success": true, "transaction_status": "UNKNOWN" }, { "id": "5", "event": "CAPTURE", "success": false, "error": { ... }, "transaction_status": "CAPTURED", "correction": { "status": "CAPTURED", "event_ids": ["4"], "remaining_capture_amount": 0, "remaining_refund_amount": 10000, "remaining_void_amount": 0 } } ] } ``` Event `3` is a capture attempt that initially appears to fail. Its `correction.status` is `AUTHORIZED` with an empty `event_ids`, meaning no correction was done and the transaction appeared to remain authorized. Event `5` is a second capture attempt, but it fails as the transaction was already captured (event `3` actually succeeded). So the event gets `success=false`, but includes a `correction` pointing to event `4`, which is the result of the successful capture. The transaction status after the second capture can be determined from `correction.status` in event `5`. In this example, you receive notifications for events `3` and `5`. You do not receive a notification for correction event `4`, so handle it when you receive the notification for event `5`. Note that in the above example you will get callbacks for event `3` and event `5`. There is no callback for the correction event `4`, this needs to be handled when receiving the callback for event `5`. [Webhooks]: /docs/checkout/webhooks [GET /v1/transaction/{id}]: /api-reference/transactions/transactions_id_get # Dintero Hosted Checkout Source: https://docs.dintero.com/docs/checkout/click-to-pay/hosted-checkout Enable Click to Pay in Dintero's Hosted Checkout via the dintero_psp.clicktopay payment method, with no SDK or custom integration required on your side. Click to Pay is offered exclusively through Dintero's hosted checkout. There is no SDK or custom integration. Enable it in the Dintero Backoffice and we handle the rest. > [!NOTE] > > Click to Pay is only supported through Dintero's own PSP (`dintero_psp.clicktopay`). It is not available via other PSP providers. ### Getting started #### Enable Click to Pay on your Dintero account Click to Pay is enabled as part of your onboarding in the Dintero Backoffice. If it is not already enabled, go to settings and payment methods, and enable Click to Pay. If you use [payment profiles](/docs/checkout/payment-profiles), ensure that Click to Pay is added to the relevant profiles. No additional setup, contracts or SDK integration is required on your side. #### Customer email For Click to Pay to be offered to a customer, the customer's email must be known during checkout. There are two ways to provide it: * Use [Checkout Express](/docs/checkout/express). The customer enters their email as part of the Express flow and Click to Pay is evaluated automatically. * Include the customer's email when creating the session (`order.billing_address.email` / `customer.email`). The email is then used to look up the customer with Click to Pay. If neither is available, the regular card form is shown without Click to Pay. #### Customer enrollment Click to Pay is only shown to customers who are enrolled with Click to Pay. Enrollment is done by the cardholder with their card issuer or through one of the Click to Pay participating sites. Cardholders can't add new cards via Dintero's solution. If the customer's email is not recognized by Click to Pay, the regular card form is shown. ### How it looks in the checkout When Click to Pay is enabled it is shown as part of the regular card form. When we have the customer's email and the customer is enrolled, we show Click to Pay with an option to enter card details manually. If the customer has chosen to be remembered we show their cards, otherwise the customer needs to authenticate using an OTP. #### Authentication Authentication is handled by Click to Pay. If the customer is enrolled they get an OTP via email and/or SMS. If they choose to be remembered they will not have to authenticate the next time. ![Click to Pay authentication](https://mintcdn.com/dintero-c3a7bfec/Uwtq7XChux8y4gPn/docs/assets/checkout/click-to-pay-login.png?fit=max\&auto=format\&n=Uwtq7XChux8y4gPn\&q=85\&s=13651caec06c5327ae317d71aa2caa51) #### Selecting a card Once the customer has authenticated they are shown a list of their enrolled cards. They can switch to another user, enter card data manually, or choose one of the stored cards to pay with. ![Click to Pay card list](https://mintcdn.com/dintero-c3a7bfec/Uwtq7XChux8y4gPn/docs/assets/checkout/click-to-pay-cards.png?fit=max\&auto=format\&n=Uwtq7XChux8y4gPn\&q=85\&s=fd59e9880833ae010ed2eb585c3e20fd) ### Authentication and 3-D Secure Depending on the card and the transaction, Click to Pay payments may be authenticated by the card network using a cryptogram that is already verified, or may require a 3-D Secure challenge. Click to Pay handles this for you, including determining when 3-D Secure is required and running the challenge flow. ### Testing #### Sandbox environment If you enable test mode and create a payment where you can use Click to Pay, we will give you some test cards that can be used to test Click to Pay behavior. The test payments will not charge any cards. #### Production testing When you are ready to test in production, you can enable Click to Pay for your production environment. These payments will actually charge the card, so you should test with a small amount and be prepared to cancel or refund the transaction after testing. To avoid exposing Click to Pay to customers while testing, you can use [a payment profile](/docs/checkout/payment-profiles) that includes Click to Pay, and only use this profile for your testing purposes. ### Further reading * [Visa Click to Pay](https://www.visa.com/clicktopay) * [Mastercard Click to Pay](https://www.mastercard.com/global/en/personal/ways-to-pay/click-to-pay.html) # Overview Source: https://docs.dintero.com/docs/checkout/click-to-pay/overview Learn how the card-network Click to Pay standard lets shoppers pay online without re-entering card details, and how to enable it through Dintero's PSP. [Hosted Checkout]: /docs/checkout/click-to-pay/hosted-checkout Click to Pay is an online checkout standard developed by the major card networks. It lets cardholders pay online without manually entering their card details, using cards stored in their Click to Pay profile across different sites. Click to Pay is offered through Dintero's own PSP and is not available via other PSP providers. ### How it works 1. Customer starts checkout and provides their email, either through [Checkout Express](/docs/checkout/express) or by including the customer's email in the session. 2. Dintero looks up the email with Click to Pay. If the customer is enrolled, their cards stored in Click to Pay are shown directly in the card form alongside the regular card input. 3. Customer selects a Click to Pay card (or enters a card manually) and completes the payment. 4. If required, the customer is taken through a 3-D Secure challenge. 5. Dintero creates an authorized transaction and the checkout session is completed. ### Requirements For Click to Pay to be offered to a customer: * The customer's email must be available during checkout, either by using [Checkout Express](/docs/checkout/express) or by including the customer's email when creating the session. * The customer must be enrolled with Click to Pay. If the email is not recognized, the regular card form is shown without the Click to Pay option. ### Liability Click to Pay supports Strong Customer Authentication (SCA) as part of the payment flow. Dintero requests SCA for all Click to Pay transactions. When SCA is completed, liability shifts to the card issuer and the merchant is protected from fraud chargebacks. If Click to Pay does not provide SCA for a given transaction, no additional authentication is performed. In that case, the standard card payment liability rules apply and the merchant bears the fraud liability. Merchants can inspect the `card.eci` field on an authorized transaction before capturing to determine the authentication level and resulting liability. A value of `05` (Visa) or `02` (Mastercard) indicates full SCA with liability shift to the issuer. `07`/`00` indicates no authentication was performed and the merchant bears fraud liability. ### Getting started Click to Pay is easy to set up. There is no SDK or custom integration to build. Enable it from the Dintero Backoffice as part of your onboarding and we handle the rest. See [Hosted Checkout] for enablement details. # Creating a checkout session Source: https://docs.dintero.com/docs/checkout/create-session Create a Dintero Checkout session with the order amount, currency, items, payment methods, and the return and callback URLs for the customer. When the customer has added all their items to the cart, and proceeded to the checkout, it's time to create a session in the Dintero system. A session contains a representation of the order: the amount, currency and items, as well as the configured payment methods, and urls for redirects and callbacks. ## Authentication To authenticate, you create a [Checkout API client] and use the credentials to [Create an access token]. The same client can be used for Sandbox mode and production. For all requests to the API set the following header: ```http theme={null} Authorization: Bearer {access_token} ``` [Checkout API client]: /docs/checkout/checkout-client [Create an access token]: /docs/checkout/checkout-client#authentication ## Create session request The session is created with an HTTP POST-request to `https://api.dintero.com/v1/accounts/{account_id}/payments/sessions-profile`. Set `Content-Type: application/json` and the authorization header. > [!NOTE] > > The Checkout API is now available under `https://api.dintero.com/v1/accounts/{account_id}/payments/`. > > The previous `https://checkout.dintero.com/v1/` base is still supported, so existing integrations continue to work without changes. > Most new accounts should have the `default` profile_id available. If you have an old account, go [here](/docs/checkout/payment-profiles) to learn how to create one. ```json theme={null} { "url": { "return_url": "https://example.com/thankyou", "callback_url": "https://example.com/callback" }, "order": { "amount": 33890, "currency": "NOK", "merchant_reference": "merchants_order_number", "items": [ { "id": "chair-1", "line_id": "1", "description": "Stablestol", "quantity": 1, "amount": 29990, "vat_amount": 6000, "vat": 25 } ], "shipping_option": { "id": "local-pick-up-point", "line_id": "local-pick-up-point", "amount": 3900, "operator": "", "title": "Pick up at a pick-up point", "delivery_method": "pick_up" } }, "express": { "shipping_options": [], "shipping_address_callback_url": "https://example.com/shipping_address_changed" }, "profile_id": "default" } ``` > [!NOTE] > > Amounts are denoted in the smallest unit for the currency, for example cents. > > * 299.90 NOK becomes 29990 > * 299 NOK becomes 29900 To learn more about the fields, check out the complete documentation for the [create session]-endpoint. Once the session is created, you can proceed with showing the checkout to the customer. ### Example response By default the response looks like this, but see the the complete documentation for the [create session]-endpoint for more details and options. ```json theme={null} { "id": "{session_id}", "url": "https://checkout.api.dintero.com/v1/view/{session_id}/" } ``` [Checkout API client]: /docs/checkout/checkout-client [create session]: /api-reference/session/checkout_session_profile_post # External payment method Source: https://docs.dintero.com/docs/checkout/dintero-external Use Dintero Checkout Express to collect customer details only, while you handle payment processing yourself with a configurable external payment option. Checkout can be used to create a session to collect customer details without initiating payment processing.\ It can be used by merchants who want to use the Dintero Checkout to collect customer details while handling the rest of the payment process themselves. > [!NOTE] > > * External payment method is only supported by Dintero Checkout Express sessions as it requires collection of customer details. > * It is required to set labels on the payment option in order for Checkout to display the payment method correctly. ### Collect shopper info flow When the payer loads the checkout they get the option to select the external payment method denoted by your own custom payment method label after they have entered their customer details, as shown below: ![Express payment option](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/express-payment-option.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=7d3cafab2bb0437edad13907856bf088) If the payer selects the payment method denoted by your custom payment method label, they are presented with your own title, description and your custom pay button that you have configured the session with. ![Express payment option revealed](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/express-payment-revealed.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=ab221487b79bd144564074ae837e39c9) When the payer proceeds with this option, they will be redirected to the `return_url` set on the session and the payer info will have been collected by Checkout. A transaction with the status `ON_HOLD` will be created from the payment request, which the merchant can later authorize in order to capture, refund or cancel the payment from Backoffice. ![Express payment transaction](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/express-payment-transaction.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=c9707f9c70cfc60a90d5484ad6609d5b) ### Example request An example request for creating a session with external payment enabled is shown below: ```http theme={null} POST https://api.dintero.com/v1/accounts/{account_id}/payments/sessions-profile Authorization: Bearer Content-Type: application/json { "url": { "return_url": "https://example.com/accept", "callback_url": "https://example.com/callback?method=GET", "merchant_terms_url": "https://example.com/terms.html" }, "order": { "amount": 10000, "currency": "NOK", "items": [ { "id": "123", "name": "Product 1", "quantity": 1, "unit_price": 10000 } ], "merchant_reference": "string" }, "profile_id": "", "configuration": { "active_payment_types": { "enabled": true }, "dintero": { "type": "payment_type", "external": { "type": "payment_product_type", "enabled": true, "payability": "payable", "display": { "payment_method_label": "Pay Later", "button_label": "Place order", "content": { "title": "Register the payment first, then pay later", "description": "You will receive an email to complete the payment" } } } } }, "express": { "shipping_options": [ { "id": "Delivery.1234", "vat": 0, "title": "Delivery address", "amount": 0, "line_id": "Delivery.1234_1", "operator": "Delivery Operator", "vat_amount": 0, "delivery_method": "delivery", "pick_up_address": { "country": "NO", "first_name": "Payee", "postal_code": "0000", "address_line": "Address 1", "postal_place": "OSLO", "phone_number": "12345678" } } ] }, "merchant": { "name": "string", "logo_url": "http://example.com" } } ``` ### Adjusting custom properties You can adjust the custom properties of the external payment method in the Backoffice by navigating to your payment profile settings under `Dintero External`. ![External payment settings](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/backoffice/external-config.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=aad3f2f36d2bca37448886a2a4542db0) # Dintero HTTP headers Source: https://docs.dintero.com/docs/checkout/dintero-http-headers Reference of recommended Dintero metadata HTTP headers and behavior-changing headers used when calling the Checkout API for tracing and integration info. The API supports various headers to either add metadata or to change the behavior of the API. ## API-wide metadata headers We recommend using the following optional HTTP headers for all requests to the Checkout API. These headers provide useful metadata about the merchant's system, which help Dintero improve our services, and also helps with troubleshooting. | Header | Description | Example value | | - | - | - | | Dintero-System-Name | The name of the ecommerce solution | woocommerce | | Dintero-System-Version | The version number of the ecommerce solution | 5.4 | | Dintero-System-Plugin-Name | The name of the ecommerce plugin | Dintero.Checkout.WooCommerce | | Dintero-System-Plugin-Version | The version number of the ecommerce plugin | 2020.11.03 | ## Endpoint-specific behavior modifiers For some requests, the API supports headers that can change the behavior. These will be mentioned in the API spec. ### Recommended | Endpoint | Recommended value | Description | | - | - | - | | [Create session from profile](/api-reference/session/checkout_session_profile_post) | `Dintero-Feature-Toggles: strict-session-amounts` | Strict validation of order amounts | # Adding discount metadata to sessions Source: https://docs.dintero.com/docs/checkout/discount-metadata Pass per-item or full-order discount details on a Dintero Checkout session using order.items[].discount_lines and order.discount_lines metadata fields. When creating sessions with discounted items, you should write the price *after* discounts, as this is what the customer is paying. If you want to add metadata to the sessions to signal that a discount has been given, you can use `order.items[*].discount_lines` if the discount is connected to a particular item or `order.discount_lines` if the discount is on the full order. See the [api spec](/api-reference/session/checkout_session_profile_post) for more details. ## Example 1: Discount added per item ```json theme={null} { "amount": 20000, "items": [ { "id": "item-1", "vat": 25, "amount": 10000, "line_id": "1", "quantity": 1, "description": "Item 1", "discount_lines": [ { "amount": 2000, "line_id": 1, "description": "Manually added 20 kroner off. // Original price 12000", "discount_id": "manual-20-kroner-off", "discount_type": "manual" } ] }, { "id": "item-2", "vat": 25, "amount": 10000, "line_id": "2", "quantity": 2, "description": "Item 2", "discount_lines": [ { "amount": 2500, "line_id": 1, "percentage": 20, "description": "New customer 20% on item 2. // Original price 12500", "discount_id": "new-customer-20-item-2", "discount_type": "customer" } ] } ] } ``` ## Example 2: Discount added on the order ```json theme={null} { "amount": 20000, "items": [ { "id": "item-1", "vat": 25, "amount": 10000, "line_id": "1", "quantity": 1, "description": "Item 1" }, { "id": "item-2", "vat": 25, "amount": 10000, "line_id": "2", "quantity": 2, "description": "Item 2" } ], "discount_lines": [ { "amount": 5000, "line_id": "dl1", "percentage": 20, "description": "20% off on the first order // The original sum was 25000", "discount_id": "first-order-20-percent", "discount_type": "customer" } ] } ``` # Show the checkout to the customer Source: https://docs.dintero.com/docs/checkout/display-checkout Render the Dintero Checkout to your customer using the session URL, with options for redirect, embedded iframe, or pop-out display modes. When the session is created, you will get a response looking like this: ```json theme={null} { "id": "P12345678.55Q4CC1WuVJdgCssZfrf5a", "url": "https://checkout.dintero.com/v1/view/P12345678.55Q4CC1WuVJdgCssZfrf5a" } ``` ## Embedding To embed this in your website, we will use the [Dintero Web SDK]. Using the SDK is quite straight forward. Include the SDK code in your site, and include this code in the website: ```html theme={null}
``` When embedded the payment will look like this: ![Embedded Checkout](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/embedded.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=08ef28b3654a32dbd70aeb452216fa56) ## Redirecting To redirect the user to the payment, point the browser to the url from the response. Alternatively, you may use the [Dintero Web SDK]. ```html theme={null}
``` When viewing the payment, the customer will see something like this: ![Express Checkout](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/express-redirect.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=b5e0e43d8fee4056060ecb104d8cd723) ## Completing the payment To complete the payment, the user must input email and address (Use [test data] for testing purposes). When the payment is completed, a transaction will be created, and you will be redirected to the `return_url` from the session. The next step is to handle the redirect and callback to the website. [test data]: /docs/checkout/checkout-testdata [Dintero Web SDK]: https://github.com/Dintero/Dintero.Checkout.Web.SDK # Display payment logos Source: https://docs.dintero.com/docs/checkout/display-payment-logos Display payment method logos on your website or app to promote trust and show available payment methods before customers enter your checkout. Display your payment method logos on your website or app to promote trust and show available payment methods before customers enter your checkout. We recommend using the Payment profile as it automatically updates when you change payment methods in your Dintero account. Use **Payment profile** to dynamically update when you add or remove payment methods from your Dintero account settings, or **Logo builder** to manually show your payment methods. > [tab] Payment profile > > Payment profile automatically shows all payment methods configured in your Dintero account. Use the generated URL to display it on your website/app. > [tab] Logo builder > > Use the logo builder to manually show your payment methods. Use the generated URL to display it on your website/app. > [tab] Documentation > > ## Overview > > The Checkout Branding API generates customized payment logo images by specifying payment types, colors, dimensions, and templates through URL parameters. > > #### Branding image URL format > > ```text theme={null} > https://checkout.dintero.com/v1/branding/logos/{logos}/variant/{variant}/color/{color}/width/{width}/{template}.svg > ``` > > ## URL parameters > > **logos** `string` *required* > > A list of payment logos separated by underscores (`_`). > > **Example:** `visa_mastercard_applepay_googlepay_vipps_mobilepay_swish_walley_klarna_billie_clicktopay` > > **Available logos:** `visa` `mastercard` `vipps` `swish` `walley` `klarna` `applepay` `googlepay` `mobilepay` `billie` `clicktopay` `two` `kravia` > > **variant** `enum` *required* > > Style variant for the logos. > > | Value | Description | > | - | - | > | `colors` | Colorful logos with full branding | > | `mono` | Monochrome version | > | `darkcolors` | Optimized for dark backgrounds | > | `logomark` | Payment logos only, no Dintero branding | > | `smallmark` | Smaller payment logos only, no Dintero branding | > > **color** `string` *required* > > RGB hex code without the `#` character. > > **Examples:** `444444`, `ee00ee` > > For `colors` and `darkcolors` variants, color applies to text and frame elements only. Does not apply to `logomark` and `smallmark` variants. > > **width** `integer` *required* > > Image width in pixels. Recommended range: 400–600px. > > **Examples:** `600`, `450`, `800` > > **template** `enum` *required* > > Layout template for the logo display. > > | Value | Description | > | - | - | > | `dintero_top_frame` | Secure payment text above, logos below | > | `logos` | Logos only, no text | > | `logo` | A single logo (the first one in `/logos/`) | > > > [!TIP] > > > > **Use your payment profile** instead of manually specifying logos. The profile automatically shows all configured payment methods and updates when you change them in your Dintero account. > > > > ```text theme={null} > > https://checkout.dintero.com/v1/branding/accounts/{account_id}/profiles/{profile_id}/variant/{variant}/color/{color}/width/{width}/{template}.svg > > ``` > > > > **Example:** > > > > ```text theme={null} > > https://checkout.dintero.com/v1/branding/accounts/P12345678/profiles/P12345678.5GdDG8rrepTQKhrEqzoRSQ/variant/colors/color/cfcfcf/width/600/dintero_top_frame.svg > > ``` > > ## Complete examples > > > [card] Variant: colors > > > > ![colors](https://checkout.dintero.com/v1/branding/logos/visa_mastercard_applepay_vipps_klarna/variant/colors/color/171717/width/600/dintero_top_frame.svg) > > > > ```text theme={null} > > https://checkout.dintero.com/v1/branding/logos/visa_mastercard_applepay_vipps_klarna/variant/colors/color/171717/width/600/dintero_top_frame.svg > > ``` > > > [card] Variant: mono > > > > ![mono](https://checkout.dintero.com/v1/branding/logos/visa_mastercard_applepay_vipps_klarna/variant/mono/color/444444/width/600/dintero_top_frame.svg) > > > > ```text theme={null} > > https://checkout.dintero.com/v1/branding/logos/visa_mastercard_applepay_vipps_klarna/variant/mono/color/444444/width/600/dintero_top_frame.svg > > ``` > > > [card] Variant: darkcolors > > > > ![Dark-theme payment logos with top frame](https://checkout.dintero.com/v1/branding/logos/visa_mastercard_applepay_vipps_klarna/variant/darkcolors/color/eeeeee/width/600/dintero_top_frame.svg) > > > > ```text theme={null} > > https://checkout.dintero.com/v1/branding/logos/visa_mastercard_applepay_vipps_klarna/variant/darkcolors/color/eeeeee/width/600/dintero_top_frame.svg > > ``` > > > [card] Variant: logomark > > > > ![logomark](https://checkout.dintero.com/v1/branding/logos/visa_mastercard_applepay_vipps_klarna/variant/logomark/color/444444/width/600/logos.svg) > > > > No Dintero branding. Secure payment text is hidden. > > > > ```text theme={null} > > https://checkout.dintero.com/v1/branding/logos/visa_mastercard_applepay_vipps_klarna/variant/logomark/color/444444/width/600/logos.svg > > ``` > > > [card] Variant: smallmark > > > > ![smallmark](https://checkout.dintero.com/v1/branding/logos/visa_mastercard_applepay_vipps_klarna/variant/smallmark/color/444444/width/600/logos.svg) > > > > Smaller logos, no Dintero branding. > > > > ```text theme={null} > > https://checkout.dintero.com/v1/branding/logos/visa_mastercard_applepay_vipps_klarna/variant/smallmark/color/444444/width/600/logos.svg > > ``` > > ## Best practices > > * Choose logos that match your accepted payment methods. > * Use the `darkcolors` variant on dark backgrounds for better visibility. > * Keep width between 400–600px for optimal display on most devices. > * Use `logomark` to minimize branding and focus on payment options; use `smallmark` for a smaller size. > * Match the `color` parameter to your website's text or border color. > * Test the generated SVG in your environment before deploying to production. # Embedded vs redirect checkout Source: https://docs.dintero.com/docs/checkout/embedVredirect Compare Dintero Checkout integration options. Hosted Redirect or Embedded iframe and pick the flow that best fits your conversion and design needs. Dintero supports three ways to present the checkout to your customers: **redirect**, **embedded**, and **pop-out** (not recommended). ## Comparison | | Redirect | Embedded | Pop-out | | - | - | - | - | | **Customer stays on your site** | No | Yes | Yes | | **Branding control** | Limited | Full | Limited | | **Implementation effort** | Low | Moderate | Low | | **Reliability** | High | High | Lower (pop-up blockers) | ## Checkout Redirect Redirect sends customers to a secure Dintero-hosted payment page. After payment, they are redirected back to your site. #### How it works **Step 1** The customer is redirected to Dintero's secure payment page. **Step 2** They complete the payment on the hosted page. **Step 3** After processing, they are redirected back to your `return_url`. #### When to use * You want a simple, low-maintenance integration. * You prefer Dintero to handle the full payment UI. * If security and compliance are major concerns, as Dintero handles all payment processing. ## Checkout Embedded Embedded checkout integrates the payment form directly into your website. Customers complete payment without leaving your site, giving you full control over the experience. #### How it works **Step 1** You render the Dintero checkout inside a container element on your page using the [Dintero Web SDK](https://github.com/Dintero/Dintero.Checkout.Web.SDK). **Step 2** The customer enters payment details without leaving your site. **Step 3** Payment processing occurs in the background. #### When to use * You want a fully branded, seamless checkout experience. * Reducing friction and keeping user engagement during checkout is a priority. * You have the resources for a slightly more complex integration. ## Checkout Pop-out (not recommended) > [!WARNING] > > Pop-out checkout is not recommended and is a legacy option. Pop-out opens a Dintero-hosted payment window as an overlay on your site. While it keeps customers on your page, it can cause issues with browser pop-up blockers and provides a less reliable experience than the redirect or embedded options. #### How it works **Step 1** The customer initiates checkout on your website. **Step 2** A Dintero-hosted payment window opens as an overlay. **Step 3** The customer completes payment in the pop-out window. **Step 4** The window closes and the customer remains on your site. # Dintero Checkout Express Source: https://docs.dintero.com/docs/checkout/express Speed up returning-customer checkout with Dintero Checkout Express by storing payment details and using one-click sessions configured via the express object. ### Introduction Checkout Express is a streamlined checkout solution designed to simplify and speed up the payment process for returning customers. By leveraging stored payment information and a simplified user interface, Checkout Express reduces friction and enhances the overall user experience, making it ideal for businesses looking to improve conversion rates and customer satisfaction. ### What is Checkout Express? Checkout Express is a checkout option that allows returning customers to complete their purchases with just a few clicks. By storing customer payment details securely, Checkout Express enables a faster, more convenient checkout process without the need for customers to re-enter their payment information every time they make a purchase. ![woo-download-plugin](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/backoffice/checkout-client/checkout_express.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=9a6efb4699a68d604a088a3f07fa3836) ### How to create an express session Add an `express` section to the request body when [creating a new session](/docs/checkout/create-session). ```json theme={null} { "url": { "return_url": "https://example.com/thankyou", "callback_url": "https://example.com/callback" }, "order": { "amount": 33890, "currency": "NOK", "merchant_reference": "merchants_order_number", "items": [ { "id": "chair-1", "line_id": "1", "description": "Stablestol", "quantity": 1, "amount": 29990, "vat_amount": 6000, "vat": 25 } ], "shipping_option": { "id": "local-pick-up-point", "line_id": "local-pick-up-point", "amount": 3900, "operator": "", "title": "Pick up at a pick-up point", "delivery_method": "pick_up" } }, "express": { "shipping_options": [{ "id": "local-pick-up-point", "line_id": "local-pick-up-point", "amount": 3900, "operator": "", "title": "Pick up at a pick-up point", "delivery_method": "pick_up" }], "shipping_address_callback_url": "https://example.com/shipping_address_changed", "shipping_mode": "shipping_required", "customer_types": ["b2b", "b2c"], }, "profile_id": "default" } ``` ### Checkout Express features Dintero **Checkout Express** offers the following features. **Customer details** * Save customer details for faster repeat purchases. * Limit customer types to `b2b`, `b2c`, or both. * Fetch company data for `b2b` customers from public registries (Norway and Denmark only). * Prefill `order.shipping_address` and `order.billing_address` if you already have the customer's details on file. **Shipping** * Define a fixed set of [shipping options](/docs/checkout/shipping-options). * Return [dynamic shipping options](/docs/checkout/shipping-address-callback) based on the customer's address, using a callback. * Set a [default shipping option](/docs/checkout/shipping-options#specifying-a-default-shipping-option). * Split orders into [multiple shipments](/docs/checkout/shipping-options-multiple-shipments). * Create [sessions without shipping options, or hide the shipping option](/docs/checkout/shipping-options#sessions-without-shipping-options-or-hiding-the-shipping-option). **Payment and checkout** * Offer one-click payments with [Apple Pay](/docs/checkout/apple-pay/apple-pay-hosted-checkout#one-click-apple-pay-in-checkout-express) and [Google Pay](/docs/checkout/google-pay/google-pay-hosted-checkout#one-click-google-pay-in-checkout-express). * Accept [discount codes](/docs/checkout/checkout-express-discount-code). * Add [custom checkboxes](#adding-custom-checkboxes), for example for newsletter signup or marketing consent. ### Adding custom checkboxes You can add up to two custom checkboxes to an Express Checkout session. Use them to collect input such as newsletter signup or marketing consent. Add a top-level `checkboxes` array when you [create the session](/api-reference/session/checkout_session_profile_post). To apply the same checkboxes to every session that uses a profile, set `configuration.checkboxes` on the [session profile](/docs/checkout/payment-profiles) instead. ![Checkout express - custom checkboxes](https://mintcdn.com/dintero-c3a7bfec/u32FcZKh3IK_yuYw/docs/assets/checkout/checkout-express.png?fit=max\&auto=format\&n=u32FcZKh3IK_yuYw\&q=85\&s=f2f381254122dd622f3091737a8d048c) ```json theme={null} { "url": { "return_url": "https://example.com/thankyou", "callback_url": "https://example.com/callback" }, "order": { "amount": 29990, "currency": "NOK", "merchant_reference": "merchants_order_number" }, "express": { "shipping_options": [] }, "checkboxes": [ { "id": "newsletter", "label": "Sign me up for the newsletter", "checked": false, "required": false, "link": { "url": "https://example.com/newsletter-terms", "text": "Newsletter terms" } } ], "profile_id": "default" } ``` | Field | Required | Description | | - | - | - | | `id` | Yes | Your ID for the checkbox. Use it to read the customer's choice later. | | `label` | Yes | Text shown next to the checkbox. Must be 2 to 99 characters. | | `checked` | No | Set to `true` to check the checkbox by default. | | `required` | No | Set to `true` to require the customer to check the checkbox before paying. | | `link` | No | Link shown with the checkbox, with `url` and `text`. | When the customer checks or unchecks a checkbox, the checkout updates the session. After payment, the transaction includes a `checkboxes` array with the `checked` value for each checkbox. Read it from the [transaction](/api-reference/transactions/transactions_id_get) to act on the customer's choice, for example to add them to your newsletter list. # Pay with gift cards in Checkout Source: https://docs.dintero.com/docs/checkout/gift-cards Let customers pay full or partial amounts with Dintero virtual gift cards in Dintero Checkout , including capture, refund, and split-payment behavior rules. Dintero Gift Cards gives your customers the option to pay either fully or partially with a gift card in your checkout. This way you can create virtual gift cards which customers can use to pay an order in your store later. > [!NOTE] > > * Only one gift card can be used to authorize a session. > * Gift cards are *not* supported for sessions where splits are specified. > * Gift cards have precedence when a transaction is partially captured or > refunded > * The refunded amount to a gift card cannot exceed what was initially > captured > > Creating a session with Dintero Gift Cards enabled is currently only supported for the following payment options: > > * `payex` > * `bambora` > * `dintero_psp` > * `klarna.klarna` > * `kravia` (allowed but cannot be used in combination with gift card) > * `two` (allowed but cannot be used in combination with gift card) > > For `kravia` and `two` these payment methods will be disabled in the checkout when the customer adds a gift card as the payment method cannot be combined with a gift card, so please ensure that the payment session also contains at least one payment option that can be used in combination with a gift card. ## Creating gift cards See the [gift card documentation](/docs/loyalty/wallet-create-gift-card) for info about creating gift cards with pin codes. ## Using gift cards in the checkout There are two ways a gift card can be used to authorize a session: * Customer provides their gift card during the checkout flow. * Merchant provides the customer gift card when the session is created. > [!NOTE] > > Native push to payment Wallets (Vipps/MobilePay/Swish) will be disabled when > gift card is enabled as the payer must "use" their gift card before > being redirected to the Wallets app. Push will be done by sending SMS > containing link to checkout. ### Customer initiated This flow allows the payer to pay their order either fully or partially using a gift card, depending on the order amount and the available balance on the card. When the payer loads the checkout they get the option to add a gift card after they have entered their personal details and before they complete the authorization, as shown below: ![Gift card input](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/gift-card-input.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=88e60fdc63c4cf6a53e612335d267386) Please note that PIN is required in this case, meaning that the payer will need to input a PIN code in order to activate the gift card. To learn more about creating a card, including cards with PIN codes, please refer to the [relevant documentation](/docs/loyalty/wallet-create-gift-card) If the gift card number and PIN entered are both correct and the gift card is valid, the gift card will be added to the session and the total amount will update to reflect the order amount minus the available balance on the gift card. In this example, the available balance was 100 NOK. The updated order amount after adding the gift card is therefore 400 - 100 = 300 NOK, as shown below: ![Gift card added](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/gift-card-added.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=8d2e858a3a9a1a6c2ce9980704bcd729) An example request for creating a session with Dintero Gift Cards enabled is shown below: ```http theme={null} POST https://api.dintero.com/v1/accounts/{account_id}/payments/sessions-profile Authorization: Bearer Content-Type: application/json { "url": { "return_url": "https://example.com/accept", "callback_url": "https://example.com/callback?method=GET", "merchant_terms_url": "https://example.com/terms.html" }, "order": { "amount": 72200, "currency": "NOK", "vat_amount": 13660, "items": [ { "amount": 72200, "quantity": 2, "line_id": "1", "description": "Forsvinnignspølse", "vat": 20, "id": "10" } ], "merchant_reference": "string" }, "configuration": { "active_payment_types": { "enabled": true }, "dintero": { "type": "payment_type", "wallets": { "type": "payment_product_type", "enabled": true } } }, "profile_id": "default", "merchant": { "name": "string", "logo_url": "http://example.com" } } ``` > [!NOTE] > > See related documentation for more information about creating sessions > > * [Create a session](/docs/checkout/create-session) > * [Checkout API reference](/api-reference/session/checkout_session_profile_post) ### Merchant initiated This flow is intended for the use case where the gift card is presented before the session is created, e.g. the payer is authenticated and the gift card is provided from the merchant CRM system. PIN is *not* required in this case, since the payer is known and authenticated. When the payer loads the checkout, it will display that a gift card has been activated and added to the session. The payer can then either proceed with the payment or remove the gift card. If they remove the gift card, they will need to input the gift card number and PIN code in order to activate it again. An example request for creating a session with Dintero Gift Cards enabled and preloaded is shown below: ```http theme={null} POST https://api.dintero.com/v1/accounts/{account_id}/payments/sessions-profile Authorization: Bearer Content-Type: application/json { "url": { "return_url": "https://example.com/accept", "callback_url": "https://example.com/callback?method=GET", "merchant_terms_url": "https://example.com/terms.html" }, "customer": { "gift_cards": { "dintero.wallets": [ { "card_id": "{wallets.card_id}" } ] } }, "order": { "amount": 72200, "currency": "NOK", "vat_amount": 13660, "items": [ { "amount": 72200, "quantity": 2, "line_id": "1", "description": "Forsvinnignspølse", "vat": 20, "id": "10" } ], "merchant_reference": "string" }, "configuration": { "active_payment_types": { "enabled": true }, "dintero": { "type": "payment_type", "wallets": { "type": "payment_product_type", "enabled": true }, "zero": { "type": "payment_product_type", "enabled": true, "payability": "payable" } } }, "profile_id": "default", "merchant": { "name": "string", "logo_url": "http://example.com" } } ``` # Dintero Hosted Checkout Source: https://docs.dintero.com/docs/checkout/google-pay/google-pay-hosted-checkout Enable Google Pay in Dintero Hosted Checkout for embedded, pop-out, or redirect flows, supported via dintero_psp.googlepay or Worldline integrations. The easiest way to use Google Pay is by using the Dintero checkout solution, where we handle the whole payment flow for you. If you are already using Dintero checkout you just need to enable Google Pay. > [!NOTE] > > Embedding Google Pay is only supported with `dintero_psp.googlepay`. If you are using Google Pay via Worldline (`bambora.googlepay` in the API), embedding is not supported. However, *pop-out* or *redirect* flows are available. ### Getting started To use Google Pay as a payment method you have to ensure you follow Google Pay APIs [Acceptable Use Policy](https://payments.developers.google.com/terms/aup) and accept Google Pay APIs [Terms of Service](https://payments.developers.google.com/terms/sellertos). You also have to [set up a Dintero account](https://onboarding.dintero.com/). #### Enable Google Pay on your Dintero account During your onboarding, Google Pay will generally be enabled as a payment method by default. If it's not enabled, you can go to settings and payment methods. There you can enable Google Pay as a payment method for your account. If you use [payment profiles](/docs/checkout/payment-profiles) ensure that Google Pay is added to the relevant profiles. #### Authentication methods Google Pay can provide both cards on file (`PAN_ONLY`) or device tokens (`CRYPTOGRAM_3DS`). Device tokens are bound to an Android device and authenticated with a 3-D Secure cryptogram. Both authentication methods are supported for hosted checkout. #### 3-D Secure Device tokens will generally not require 3-D Secure authentication as they are already authenticated, while `PAN_ONLY` will generally require 3-D Secure authentication. For hosted checkout we will handle 3-D Secure for you, both determining if it is required as well as handling the authentication flow. #### One click Google Pay in Checkout Express For [Checkout Express sessions](/docs/checkout/express) we support a one click Google Pay checkout flow where the customer can pay by clicking a Google Pay button that is shown above the customer data form. When the customer clicks this button the session is updated with customer details from Google Pay and the customer selects a shipping option in the Google Pay UI. Since Google Pay's express features behaves a bit differently from the default Checkout Express flow this requires an opt in property in the session configuration, the `allow_express_wallet_payment` must be set to `true`. Google Pay can still be used for payment in Express Checkout when this flag is not set. Google Pay will then be shown next to the other payment options after the customer has entered their address details manually. ### Testing #### Sandbox environment If you enable test mode and create a payment with Google Pay, you will get a dialog where you can select the card with the desired behavior. This uses a Google Pay sandbox to simulate getting a payload from Google Pay. The test payments will not charge any cards. #### Production testing Once you are ready to test in production you can enable Google Pay for production and try payments. Note that this will actually charge your card, but you can cancel or refund the payment after testing. If you want to avoid exposing Google Pay to customers while testing in production you can set up a [payment profiles](/docs/checkout/payment-profiles) and add Google Pay to a profile that isn't used for customers. # Native app integration Source: https://docs.dintero.com/docs/checkout/google-pay/google-pay-native-app Integrate Google Pay directly in your Android app or website with Dintero PSP processing the payment and your code controlling the Google Pay UI. Native app integration gives you complete control over the Google Pay user experience within your mobile application or website. While Dintero handles the payment processing, you implement the Google Pay interface directly, providing a seamless experience for your customers. > [!NOTE] > > Native app integration with Google Pay is supported only via `dintero_psp.googlepay`. If you are using Worldline (`bambora.googlepay` in the API), native app integration is not available. ### Prerequisites #### Google Pay merchant onboarding Before implementing Google Pay in your app, you must complete Google's merchant onboarding process: 1. Create a [Google Pay API developer account](https://pay.google.com/business/console) 2. Complete Google's merchant verification process 3. Submit your integration for Google's review and approval 4. Receive approval to process live transactions **Note**: This process can take several weeks, so plan accordingly. You can begin development using Google's sandbox environment while awaiting approval. #### Enable Google Pay on your Dintero account During your onboarding, Google Pay will generally be enabled as a payment method by default. If it's not enabled, you can go to settings and payment methods. There you can enable Google Pay as a payment method for your account. If you use [payment profiles](/docs/checkout/payment-profiles) ensure that Google Pay is added to the relevant profiles. ### Integration with Dintero Below we'll describe how you can implement the payment flow yourself. The flow is as follows: 1. User initiates payment 2. You request payment data from Google Pay 3. Google Pay returns the payment data 4. You post the payment data to Dintero 5. If required, you ask user to perform 3-D Secure challenge 6. You initiate the payment ```mermaid theme={null} sequenceDiagram actor C as Customer participant A as Your app participant GP as Google Pay participant DC as Dintero Checkout participant DPS as Dintero PSP Service participant 3DS as 3-D Secure C->>A: User initiates payment A->>GP: Request payment data GP-->>A: Payment data A->>DC: Post payment data DC-->>A: Auth methods opt If 3-D Secure is required A->>3DS: Open hosted 3DS solution using in-app web ui 3DS-->>C: Present challenge to customer C->>3DS: Complete 3DS challenge 3DS-->>DPS: Notify Dintero about 3DS result DPS-->>A: Redirect to app with 3DS result end A->>DC: Initiate checkout payment DC-->>A: Payment result ``` #### Dintero API [create a session]: /docs/checkout/create-session [payment in app]: /docs/checkout/payment-in-app To integrate directly with Dintero you can check the [API reference](/api-reference/session/checkout_session_profile_post). To enable payments with Dintero you first need to [create a session] with Dintero. Also see how you can configure your session for [payment in app]. Once you have a session you can get [payment operations](/checkout-api/view/checkout_sid_payments_product_type_post). For Google Pay, you want to get the operation with a rel of `submit-dintero-psp-googlepay`. This operation will contain the endpoint to use for submitting the Google Pay payment data, as well as the fields you need to configure Google Pay: * `supported_networks`: The supported networks for Google Pay * `gateway_merchant_id`: This is your gateway merchant ID, which is your account ID. In production this should start with a `P`, in test mode it should start with a `T` * `gateway_id`: The gateway ID to use, this will always be `dintero` * `googlepay_merchant_id`: For native implementation you should ignore this field * `href`: This is the URL you should post the Google Pay payment data to Example request (note, there is no body or content type in this POST request): ```http theme={null} POST https://checkout.dintero.com/v1/view/{session_id}/payments/dintero_psp.googlepay ``` ```json theme={null} { "operations": [ { "href": "https://payments.psp.dintero.com/google-pay/v1/{account_id}/payments/{payment_id}/transactions?access_token={access_token}", "method": "POST", "rel": "submit-dintero-psp-googlepay", "content_type": "application/json", "googlepay_merchant_id": "{googlepay_merchant_id}", "supported_networks": [ "VISA", "MASTERCARD" ], "gateway_id": "dintero", "gateway_merchant_id": "{gateway_merchant_id}" } ] } ``` #### Setting up Google Pay See the [Google Pay Android overview](https://developers.google.com/pay/api/android/overview) for an overview of how it works, the payment flow, and various resources. You can follow the [tutorial from Google Pay](https://developers.google.com/pay/api/android/guides/tutorial) to configure Google Pay for Android. Below we'll describe some of the steps for configuring Google Pay, specifically which values to use and where to find them. ##### Gateway ID and gateway merchant ID Set the gateway and gateway merchant ID to ensure you use Dintero as the gateway. The gateway should always be `dintero` and will be returned in `gateway_id`. The gateway merchant ID is returned in `gateway_merchant_id` and should be your account ID. ```kotlin theme={null} private fun gatewayTokenizationSpecification(): JSONObject { return JSONObject().apply { put("type", "PAYMENT_GATEWAY") put("parameters", JSONObject(mapOf( "gateway" to "dintero", "gatewayMerchantId" to "YOUR_DINTERO_ACCOUNT_ID"))) } } ``` Replace `YOUR_DINTERO_ACCOUNT_ID` with your actual Dintero account ID. The correct value is returned as `gateway_merchant_id` in the payment operation. You can also find your account ID by logging in to [Backoffice](https://backoffice.dintero.com/), where it will be displayed in the upper right corner. It is an 8-digit number with a preceding P or T (e.g., P12345678). Use PXXXXXXXX for production and TXXXXXXXX for testing (e.g., when in test mode). ##### Authorization methods Google Pay can provide both cards on file (`PAN_ONLY`) or device tokens (`CRYPTOGRAM_3DS`). Device tokens are tokens bound to an Android device that is authenticated with a 3-D Secure cryptogram. Dintero supports both methods. Device tokens will generally not require 3-D Secure authentication as they are already authenticated, while `PAN_ONLY` will generally require 3-D Secure authentication. For native apps it is recommended to at least use `CRYPTOGRAM_3DS`. To support both methods for maximum compatibility you can do the following: > [!NOTE] > > **Visa and liability shift**: If liability shift is not enabled, Visa transactions may return `PAN_ONLY` instead of `CRYPTOGRAM_3DS`, which can trigger a 3-D Secure challenge. Enable Visa liability shift in your Google Pay console to allow `CRYPTOGRAM_3DS` tokens and reduce the need for 3-D Secure. > See Google's guide: [Liability shift opt-in](https://developers.google.com/pay/api/android/guides/resources/shift-liability-to-issuer#liability-shift-opt-in). ```kotlin theme={null} private val allowedCardAuthMethods = JSONArray(listOf( "PAN_ONLY", "CRYPTOGRAM_3DS")) ``` ##### Card networks You have to provide the card networks that you want to accept to Google Pay. While you can choose to not support all card networks, you should not provide any networks not supported by Dintero. The card networks supported by Dintero are returned as `supported_networks` in the payment operation. ```kotlin theme={null} private val allowedCardNetworks = JSONArray(listOf( "MASTERCARD", "VISA")) ``` ##### Submitting payment token Once everything is configured you can request a payment token from Google as described in their [tutorial](https://developers.google.com/pay/api/android/guides/tutorial). You should then receive the [payment data](https://developers.google.com/pay/api/web/reference/response-objects#PaymentData) that you should submit to Dintero. Use the `href` returned in the [payment operations](/checkout-api/view/checkout_sid_payments_product_type_post) for the `submit-dintero-psp-googlepay` operation, see the [API reference](/psp-wallet-api/google-pay/googlePayPost_Google_Pay_Transaction) Extract the `access_token` query parameter from the operation `href` and post the payment data. Please remove the `access_token` query param from the URL before posting payment data. Ensure you send the `payment_data` as a JSON string. ```http theme={null} POST https://payments.psp.dintero.com/google-pay/v1/{account_id}/payments/{payment_id}/transactions Authorization: {access_token} Content-Type: application/json Body: { "reference": "{unique id}", "payment_data": "{Google Pay payment data}" } ``` Example response body where 3-D Secure is not needed, your application can continue to the initiate checkout payment step. ```json theme={null} { "payment_id": "{payment_id}", "transaction_id": "{transaction_id}", "auth_method": { "type": "NONE", "payment_id": "{payment_id}", "transaction_id": "{transaction_id}" }, "operations": [] } ``` Example response body where 3-D Secure is required, your application will have to show a web UI where the customer can complete 3-D Secure. ```json theme={null} { "payment_id": "{payment_id}", "transaction_id": "{transaction_id}", "auth_method": { "type": "SECURE_3D_AUTHENTICATION", "payment_id": "{payment_id}", "transaction_id": "{transaction_id}" }, "operations": [ { "href": "{url_to_hosted_3ds_session}", "method": "GET", "rel": "3d-secure-init-hosted" } ] } ``` ##### 3-D Secure You need to support performing 3-D Secure authentication even if you only support device tokens, as there can be instances where additional authentication is required. ##### Performing 3-D Secure The response when you post payment data will let you know if you need to perform 3-D Secure or not. If `auth_method.type` is `NONE` there should be no need for 3-D Secure, otherwise you need to find the operation with a `rel` of `3d-secure-init-hosted` and open the provided URL in an iframe. When the user has completed 3-D Secure you will receive a redirect back to the return URL used for the session. The redirect will contain a query parameter `status_3ds` with a value indicating the result of the 3-D Secure challenge: `3DS_SUCCESS`, `3DS_FAILURE`, or `3DS_CANCEL`. When 3-D Secure is finished you can continue and initiate the checkout payment. ##### Initiate checkout payment After posting the Google Pay payment data to Dintero and performing 3-D Secure (if required), the next step is to [initiate the checkout payment](/checkout-api/payment/checkout_sid_pay_post). Make sure you set the `payment_product_type` to `dintero_psp.googlepay`. The `psp_transaction_id` will be returned when you submit the payment token data to Dintero. ```http theme={null} POST https://api.dintero.com/v1/accounts/{account_id}/payments/sessions/{session_id}/pay Content-Type: application/json Body: { "payment_product_type": "dintero_psp.googlepay", "psp_transaction_id": "{transaction_id}" } ``` After posting to the initiate checkout payment endpoint the session is completed and has created an authorized transaction. The payment response will contain a `return_url` but there is no need to follow or call it. ### Testing #### Sandbox environment You can use Google Pay's test environment during development to test your integration. Ensure you use the correct account ID when in test mode (it should start with a T). Test amounts for triggering errors: * 401: Soft declined. * 5XX: If amount starts with 5, the two last digits will be the response code from Dintero * 501: Response code 01. * 502: Response code 02. * etc. The test payments will not charge any cards. Make sure to verify that you handle 3-D Secure and handle the redirect correctly. #### Production testing Once you are ready to test in production you can enable Google Pay for production and try payments. Note that this will actually charge your card, but you can cancel or refund the payment after testing. If you want to avoid exposing Google Pay to customers while testing in production you can set up a [payment profiles](/docs/checkout/payment-profiles) and add Google Pay to a profile that isn't used for customers. ### Best practices Make sure you follow the following best practices. * Never log or store Google Pay tokens * Implement proper error handling to avoid exposing sensitive information * Validate all payment responses on your server ### Example application See [https://github.com/Dintero/dintero-android-native-example](https://github.com/Dintero/dintero-android-native-example) for an example application on how to accept Google Pay payments. ## Troubleshooting ### Common issues * Ensure you have configured Google Pay with your own Google Pay merchant ID * Verify gatewayMerchantId matches your Dintero account * Check that Google Pay is enabled in your Dintero account * Ensure proper authorization method configuration * Ensure Google Pay is not configured with networks not supported by Dintero #### More resources * [Google Pay on Android](https://developers.google.com/pay/api/android) * [Google Pay integration checklist](https://developers.google.com/pay/api/android/guides/test-and-deploy/integration-checklist) * [Google Pay brand guidelines](https://developers.google.com/pay/api/android/guides/brand-guidelines) * [API reference](/api-reference/session/checkout_session_profile_post) * [Test cards](/docs/checkout/testdata/dintero-psp/checkout-dintero-cards-testdata) # Overview Source: https://docs.dintero.com/docs/checkout/google-pay/google-pay-overview Compare Google Pay integration options with Dintero Checkout, including hosted, embedded, and native Android app integration via dintero_psp or Worldline. [Hosted Checkout]: /docs/checkout/google-pay/google-pay-hosted-checkout [Native App Integration]: /docs/checkout/google-pay/google-pay-native-app Google Pay™ is a digital wallet platform and online payment system that allows users to make payments using cards stored in their Google accounts. It provides a fast, secure, and convenient way for customers to pay for goods and services both online and in physical stores. ### Integration options with Dintero There are primarily two ways to support Google Pay in your payment flow: hosted checkout or native app integration. #### 1. Hosted checkout If you are using our checkout solution you can add Google Pay without any need to integrate with Google Pay. You just enable Google Pay and we take care of the rest. #### 2. Native app integration If you need more control over the payment experience, such as in a native mobile application, you can integrate with Google Pay yourself. ### Google Pay feature support by PSP provider Dintero supports Google Pay payments through both our own PSP and via Worldline. The table below shows which integration types are supported by each provider. | PSP | Native | Hosted | Hosted Embedded | | - | :-: | :-: | :-: | | Dintero | ✅ | ✅ | ✅ | | Worldline | ❌ | ✅ | ❌ | ### Liability Google Pay processes payments through the customer's underlying card (credit, debit, or prepaid) stored in their Google account. Transactions are subject to card network chargeback rules. Customers can dispute charges through their card issuer following the same process and liability rules as regular card payments. Liability shift (where the risk is on the card issuer rather than the merchant) depends on how the card is authenticated at the time of payment: * **Cards authenticated with device security** (e.g., a card stored on a mobile device secured with biometrics): These payments include a device-generated cryptogram that satisfies Strong Customer Authentication (SCA). Liability shift typically applies without requiring additional 3D Secure authentication. * **Cards stored in a Google account without device-level security** (e.g., a card added via a desktop browser): These payments carry the card number without a device cryptogram. Additional 3D Secure authentication is required to achieve liability shift. Without it, the merchant bears fraud liability. Merchants can inspect the `card.eci` field on an authorized transaction before capturing to determine the authentication level and resulting liability. A value of `05` (Visa) or `02` (Mastercard) indicates full SCA with liability shift to the issuer. `06`/`01` indicates authentication was attempted. `07`/`00` indicates no authentication was performed and the merchant bears fraud liability. ### Next steps * Learn about [Hosted Checkout] for a simple, managed integration * Explore [Native App Integration] for native Android implementation # Creating a terminal session Source: https://docs.dintero.com/docs/checkout/in-person/creating-terminal-session Build the request body for an in-person card payment on a Dintero terminal, including store identifiers, sale, and refund examples. A terminal session is a regular Checkout session with three additions: 1. A [payment profile](/docs/checkout/payment-profiles) that enables **Card (Present)**. 2. The `order.store` identifiers that route the payment to a specific terminal. 3. A `publish` configuration that initiates the payment on the terminal, and `configuration.channel: in_store` to classify it as an in-store payment. The sections below cover each piece in order, then bring them together in a [full request](#sale-full-request). ## Endpoint ```http theme={null} POST https://api.dintero.com/v1/accounts/{account_id}/payments/sessions-profile Authorization: Bearer Content-Type: application/json ``` > [!NOTE] > > The Checkout API is now available under `https://api.dintero.com/v1/accounts/{account_id}/payments/`. > > The previous `https://checkout.dintero.com/v1/` base is still supported, so existing integrations continue to work without changes. See [POST /sessions-profile](/api-reference/session/checkout_session_profile_post) for the full schema. ## 1. Enable the payment method (payment profile) In-person payments are enabled on a [payment profile](/docs/checkout/payment-profiles) in Dintero Backoffice → **Settings** → **Payment Profiles**. Enable **Card (Present)** on the profile you reference with `profile_id`, and the session accepts terminal payments without any payment-method configuration in the request body. > [!NOTE] > > Managing payment methods through profiles means you can add or change methods without redeploying integration code. Avoid sending a hardcoded `configuration.seitatech` block on the request - let the profile drive the payment method. ## 2. Route to a terminal (`order.store` identifiers) The payment profile toggles the payment method on; `order.store` says which physical terminal the payment runs on. The terminal ID belongs in `order.store.terminal_id`. ```json theme={null} { "order": { "store": { "id": "oslo-center", "terminal_id": "T12345678-T0010", "payout_destination_id": "seller-1" } } } ``` The three fields are required together for in-person payments: | Field | Description | | - | - | | `order.store.id` | Your merchant store identifier - the `store_id` you sent when creating the store, the same one you already use in the payment-link flow. Not the Dintero-generated `id`. | | `order.store.terminal_id` | The `terminal_id` returned when the terminal was registered. The format is your Dintero account ID (`T` prefix for sandbox, `P` for production), a hyphen, then the terminal ID. For example `T12345678-T0010`. Must be enrolled and linked to the store. | | `order.store.payout_destination_id` | The `payout_destination_id` linked to the store. | > [!NOTE] > > The `order.store.id` you use today in the payment-link flow is fine to keep using - in-person payments use the same store identifier. You just need to add `terminal_id` and `payout_destination_id` alongside it. ## 3. Initiate the payment on the terminal (`publish`) Add a `publish` push/terminal configuration to the session request to initiate the payment on the terminal as soon as the session is created. Set `configuration.channel` to `in_store` as well. ```json theme={null} { "configuration": { "channel": "in_store", "publish": [ { "channel": "push", "type": "terminal" } ] } } ``` This works whether `seitatech.in_person` is the only enabled payment method or there are other payment methods on the payment profile. The `publish` configuration initiates the payment on the terminal in both cases. If other payment methods are enabled on the session and `seitatech.in_person` fails validation, the session is created but the payment is not initiated on the terminal. See [The terminal does not prompt the customer](/docs/checkout/in-person/terminal-troubleshooting#the-terminal-does-not-prompt-the-customer). ## Sale: full request This example combines all three pieces to create a session that immediately triggers a payment on terminal `T12345678-T0010` at store `oslo-center` for 399.00 NOK. The payment profile referenced by `profile_id` has Card (Present) enabled, and the `publish` configuration initiates the payment on the terminal. ```json lines highlight={21-36} theme={null} { "url": { "return_url": "https://yourpos.example.com/payment/return", "callback_url": "https://yourpos.example.com/payment/callback" }, "order": { "amount": 39900, "currency": "NOK", "merchant_reference": "order-12345", "items": [ { "id": "sku-coffee-001", "line_id": "1", "description": "Premium Coffee Beans 1kg", "quantity": 2, "amount": 39900, "vat_amount": 4275, "vat": 12 } ], "store": { "id": "oslo-center", "terminal_id": "T12345678-T0010", "payout_destination_id": "seller-1" } }, "configuration": { "channel": "in_store", "publish": [ { "channel": "push", "type": "terminal" } ] }, "profile_id": "your_profile_id" } ``` > [!NOTE] > > Amounts are in the smallest unit of the currency. `39900` is 399.00 NOK. You can also use `DKK` or `SEK`. The currency must match the country of the payout destination. See [supported countries and currencies](/docs/checkout/in-person/overview#supported-countries-and-currencies). ## After you create the session ### Cancelling a payment Once Dintero starts the transaction on the terminal, you can cancel it in two ways: * **From the terminal**: the customer or operator cancels directly on the device. * **Via the API**: call [POST /sessions/\{session_id}/cancel](/api-reference/session/checkout_session_cancel_post) to cancel the session programmatically. If the payment is successfully cancelled, the transaction is created with status `DECLINED`. ### Receiving the result Use the `callback_url` and webhooks to know when the transaction is captured. In-person payments are processed as a sale, so the transaction is authorized and captured in one step. `configuration.auto_capture` is ignored for `seitatech.in_person`. See [Checkout webhooks](/docs/checkout/checkout-webhooks) and [transaction management](/docs/checkout/transaction-management). ## Refund `seitatech.in_person` supports both full and partial refunds. The refund requires a `terminal_id` in the request body, and the cardholder must be present at the terminal to approve by tapping their card. Refunds use the standard [refund endpoint](/api-reference/transactions/transactions_id_refund_post): ```http theme={null} POST https://api.dintero.com/v1/accounts/{account_id}/payments/transactions/{transaction_id}/refund Authorization: Bearer Content-Type: application/json ``` ```json theme={null} { "amount": 19950, "reason": "Partial return", "terminal_id": "T12345678-T0010", "items": [ { "line_id": "1", "amount": 19950, "quantity": 1 } ] } ``` ### Refund flow 1. Your server sends the refund request. The API returns `202 Accepted` and the transaction receives an `INITIATE_REFUND` event while the status remains `CAPTURED`. 2. The terminal prompts the cardholder to approve the refund by tapping their card. 3. The refund completes when the cardholder approves, or is voided if they cancel on the terminal. ### Terminal requirements The terminal must be active on the same `payout_destination_id` as the original transaction. It does not have to be the same terminal that processed the original payment. A valid `terminal_id` always returns `202 Accepted`. If the terminal is offline, the `INITIATE_REFUND` event expires after 120 seconds and the transaction is updated with a failed refund event. > [!NOTE] > > Use `callback_url` with `report_event=REFUND` or a [webhooks subscription](/docs/checkout/checkout-webhooks) to receive a notification when the refund status is updated. ## Quick reference: answers to common integration questions | Question | Answer | | - | - | | How do I enable in-person payments? | Enable Card (Present) on a [payment profile](/docs/checkout/payment-profiles) in Backoffice and reference it with `profile_id`. | | Where does `terminal_id` go? | `order.store.terminal_id`. | | Is `order.store.id` enough? | Yes - reuse the same store ID you already send. Just add `terminal_id` and `payout_destination_id` alongside it. | | How do I trigger a sale? | Create the session against an in-person payment profile with the `order.store` identifiers and a `publish` push/terminal configuration. The terminal prompts the customer. Also set `configuration.channel` to `in_store` so the transaction is recorded as an in-store payment. | | Why didn't the terminal prompt the customer? | If the profile has other payment methods enabled, an invalid in-person request disables `seitatech.in_person` instead of failing. Check `payability_disabled_reasons` on the session. See [The terminal does not prompt the customer](/docs/checkout/in-person/terminal-troubleshooting#the-terminal-does-not-prompt-the-customer). | | How do I cancel a payment? | Cancel from the terminal, or call [POST /sessions/\{session_id}/cancel](/api-reference/session/checkout_session_cancel_post) via the API. The transaction status will be `DECLINED`. | | How do I refund? | [POST /v1/transactions/\{transaction_id}/refund](api-reference/transactions/transactions_id_refund_post). Both full and partial refunds are supported. Include `terminal_id` in the request body. The cardholder must approve on the terminal. | | When is the refund complete? | When the cardholder approves on the terminal. A valid `terminal_id` always returns `202 Accepted`. If the terminal is offline, the `INITIATE_REFUND` event expires after 120 seconds and the transaction is updated with a failed refund event. Use `callback_url` with `report_event=REFUND` or webhooks to get notified. | | How do I test a terminal payment? | Use a [simulated terminal](/docs/checkout/in-person/simulated-terminals) to test without hardware. To test with a physical sandbox terminal, use the Visa CDET Android app to simulate contactless test cards against a sandbox terminal. See [In-person payment test data](/docs/checkout/testdata/other/checkout-in-person-testdata). | # In-person payments overview Source: https://docs.dintero.com/docs/checkout/in-person/overview Accept card payments on physical Dintero terminals using the Checkout API. Reuse your session flow with a Seitatech configuration to drive the terminal. In-person payments let you charge a customer on a physical payment terminal using the same Checkout API you already use for online payments. You create a session, point it at a specific terminal, and the terminal prompts the customer to tap, insert, or swipe their card. The integration reuses your existing Checkout client, session profile, and transaction management. The only difference is that the order references a store and terminal, and the payment is completed on the terminal instead of in a hosted page. > [!NOTE] > > In-person payments are powered by Seitatech and use the `seitatech.in_person` payment type. Backoffice shows this payment method as **Card (Present)**. The two names refer to the same payment method. The terminals are physical card readers provisioned by Dintero. ## How it works **1. Create a session** Send a `POST` to `/v1/sessions-profile` with your usual order details, plus `order.store.id`, `order.store.terminal_id`, and `order.store.payout_destination_id`. Enable **Card (Present)** on your [payment profile](/docs/checkout/payment-profiles) and reference it with `profile_id`. **2. Terminal prompts the customer** Add a `publish` push/terminal configuration to the session request to initiate the payment on the terminal. Set `configuration.channel` to `in_store` so the transaction is recorded as an in-store payment. **3. Customer pays on the terminal** The customer completes the payment on the terminal. In-person payments are processed as a sale: the transaction is authorized and captured in one step. **4. Receive the result** Use your `callback_url` and webhooks to be notified when the transaction is authorized and captured. Manage refunds and voids through the standard Transactions API. ## Supported countries and currencies In-person payments support the following countries and currencies. | Country | Currency | | - | - | | Norway | NOK | | Denmark | DKK | | Sweden | SEK | DKK and SEK work the same way as NOK. The session request, terminal flow, and transaction management are identical for all three currencies. > [!WARNING] > > The session currency must currently match the country of the payout destination. For example, a payout destination in Sweden only accepts `SEK`. If `order.currency` does not match, the session request fails with an error. ## Prerequisites Before you can take a payment on a terminal, you need: * An active Dintero account with In-Person Payments enabled. * A **payout destination** for the merchant of record. KYC must be completed. * A **store** linked to the payout destination. * A **terminal** registered to the store. * A **Checkout API client** with the `checkout` scope. * A **payment profile** that has Card (Present) enabled. See [payment profiles](/docs/checkout/payment-profiles). See [terminal onboarding](/docs/checkout/in-person/terminal-onboarding) for how to set up the payout destination, store, and terminal. > [!NOTE] > > If you are a Dintero partner onboarding a new merchant, you can request in-person payments during the merchant invite flow. See [Requesting in-person payments for a new merchant](/docs/partners/inviting-merchants#requesting-in-person-payments-for-a-new-merchant). ## Identifiers you'll use | Identifier | Where it comes from | Where it goes in the request | | - | - | - | | `payout_destination_id` | Created in Backoffice during onboarding | `order.store.payout_destination_id` | | `store.id` | Created in Backoffice or via the management API | `order.store.id` | | `terminal_id` | Assigned when the terminal is registered | `order.store.terminal_id` | The combination of these three values determines which physical terminal the payment is routed to. ## Dintero and your POS system Dintero provides the payment terminal, card acquiring, and the Checkout API that starts payments on the terminal. Dintero does not provide a POS app or a cash register. You still need a POS system that builds the cart, sends the order to Dintero, and meets the cash register rules in your country. | Task | Handled by | | - | - | | Taking the card payment on the terminal | Dintero | | Closing and settling the terminal's card batch with the acquirer (`end_of_day`) | Dintero | | Printing the card payment receipt | Dintero terminal | | Cart, checkout flow, and sending the order to the Checkout API | Your POS system | | Sales receipt with item lines and VAT | Your POS system | | Cash register requirements, such as a certified cash register, control unit, Z report, and electronic journal | Your POS system or cash register provider | The terminal's `end_of_day` operation settles card payments. It is not a Z report. Your POS system can print its own sales receipt on the terminal's printer with [`print_text`](/docs/checkout/in-person/terminal-operations#print-text), but Dintero does not compose or check that content. Country-specific cash register rules apply to your cash register, not to the Dintero terminal. In Sweden, for example, the control unit requirement and the cash register rules that take effect on 1 January 2027 are the responsibility of your cash register provider. ## What's next > [card] [Onboard a terminal](/docs/checkout/in-person/terminal-onboarding) > > Create a payout destination, register a store, and link a terminal. > [card] [Create a terminal session](/docs/checkout/in-person/creating-terminal-session) > > Build the session payload, trigger the terminal, and handle refunds. # Test with a simulated terminal Source: https://docs.dintero.com/docs/checkout/in-person/simulated-terminals Create a simulated terminal on a sandbox account to test in-person payment flows without a physical terminal. A simulated terminal lets you test in-person payments on a sandbox account without a physical terminal. You register it the same way as a physical terminal, but with a special serial number. > [!NOTE] > > Simulated terminals are available on sandbox accounts (`T` prefix) only. ## Create a simulated terminal [`POST /v1/accounts/{aid}/terminals`](/api-reference/account-terminals/aid_account_management_terminals_post) Set `device_serial_number` to `SIMULATED-{account_id}-` followed by a 3-digit number, for example `SIMULATED-T12345678-001`. ```bash Request wrap theme={null} curl -X POST https://api.dintero.com/v1/accounts/T12345678/terminals \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "device_serial_number": "SIMULATED-T12345678-001", "store_id": "oslo-center" }' ``` The terminal is `ACTIVE` immediately. You do not need to activate it. Keep `terminal_id` from the response. Use it as `order.store.terminal_id` when you create a payment. ## Create a payment Create a [terminal session](/docs/checkout/in-person/creating-terminal-session) with the simulated terminal's `terminal_id` in `order.store.terminal_id`. The simulated terminal answers automatically. Set `order.amount` to one of the [test amounts](#payment-responses) to choose the outcome. [`POST /sessions-profile`](/api-reference/session/checkout_session_profile_post) ```bash Request wrap theme={null} curl -X POST https://api.dintero.com/v1/accounts/T12345678/payments/sessions-profile \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "url": { "return_url": "https://yourpos.example.com/payment/return", "callback_url": "https://yourpos.example.com/payment/callback" }, "order": { "amount": 39900, "currency": "NOK", "merchant_reference": "order-12345", "items": [ { "id": "sku-coffee-001", "line_id": "1", "description": "Premium Coffee Beans 1kg", "quantity": 2, "amount": 39900, "vat_amount": 4275, "vat": 12 } ], "store": { "id": "oslo-center", "terminal_id": "T12345678-T0010", "payout_destination_id": "seller-1" } }, "configuration": { "channel": "in_store", "publish": [ { "channel": "push", "type": "terminal" } ] }, "profile_id": "default" }' ``` This example uses `399.00` NOK, so the payment is approved with a Visa card. ## Payment responses A simulated terminal answers a payment automatically. The session amount decides the outcome and the card brand. | Amount | Outcome | | - | - | | 9901.00 | The payment is declined. | | 9902.00 | The terminal reports a different amount than requested, and the transaction fails. | | 9903.00 | The terminal reports a different currency than requested. | | 9904.00 | The terminal does not respond, and the transaction fails. | | 9905.00 | The payment is approved with a BankAxept card. | | 9906.00 | The payment is approved with a Mastercard card. | | Any other amount | The payment is approved with a Visa card. | > [!NOTE] > > Amounts are shown in major units. In the API, send them in minor units, for example `990100` for `9901.00`. ## Refunds and terminal operations You can [refund](/api-reference/transactions/transactions_id_refund_post) a captured transaction from a successful simulated-terminal payment. For `seitatech.in_person` refunds, include `terminal_id`; the simulated terminal approves automatically. You can also send [terminal operations](/docs/checkout/in-person/terminal-operations) to a simulated terminal. The simulator does not provide failure scenarios for refunds or terminal operations, but invalid requests can still return API errors. ## Find simulated terminals Filter by `device_model=SIMULATED`: [`GET /v1/accounts/{aid}/terminals`](/api-reference/account-terminals/aid_account_management_terminals_get) ```bash Request wrap theme={null} curl https://api.dintero.com/v1/accounts/T12345678/terminals?device_model=SIMULATED \ -H "Authorization: Bearer " ``` # Terminal onboarding Source: https://docs.dintero.com/docs/checkout/in-person/terminal-onboarding Set up payout destinations, stores, and terminals so the Dintero Checkout API can route in-person payments to a specific physical card reader. Before you can charge a customer on a terminal, the terminal has to be linked to a store, and the store has to be linked to a payout destination. You can complete the whole onboarding in Backoffice, or automate the store and terminal steps via the management API. > [tab] Backoffice > > **1. Onboard a payout destination** > > The payout destination is the seller of record - the entity that receives the funds. KYC is a one-time step per legal entity. > > 1. Go to **Payout destination** and click the **+ Payout destination** button. > 2. **Select a business**. Make sure the **country** is correct. Enter your own **Payout destination ID**, choose the **Payout frequency**, enter an email address (Optional. If an email is entered, Dintero will automatically send the recipient the KYC link after saving), and click **Save**. > 3. After saving, a link is generated to complete KYC. > 4. Open the link and complete the KYC form, including signing the agreement. The payout destination is ready when the status is **Approved**. > > **2. Create a store** > > A store represents a physical location. Stores are linked to one payout destination. > > 1. Go to **In-person payments**, this will default to the **Stores** page, and click the **+ Add Store** button. > 2. Select the **Payout destination** you onboarded in Step 1, enter the **Contact details**, and click **Save**. > 3. When the status of the store is **Active** (can take a couple of hours), your store has been successfully added. > > **3. Add a terminal** > > Each terminal is connected to a single store. Connect the terminal to the internet first: it cannot sync with Dintero until it is online. > > 1. In Backoffice, go to **In-person payments**, then **Terminals**, and click the **+ Add Terminal** button. > > 2. Select the **Store**, enter the terminal's **Serial number**, and click **Save**. > > 3. The Terminals page shows the terminal with the status **Pending**. Once synced, the status is replaced with an **Activate terminal** button. > > 4. Click **Activate terminal** and **follow the on-screen instructions**. > > 5. When the status of your terminal is **Activated**, your terminal has been successfully added. > > > [accordion] Set up the physical terminal (same instructions as Backoffice) > > > > Backoffice shows these steps on screen when you click **Activate terminal**. Follow the instructions there, and use this as a reference if you need them outside Backoffice. > > > > **4. Connect to Wi-Fi** > > > > On the terminal > > > > 1. Turn on the terminal, swipe **↑ Up** on the display, and open the **iNfiniPay** app. The terminal installs the software and restarts. > > > > 2. Tap the **☰ Menu icon** in the top-right corner of the screen. > > > > 3. Go to **Network Settings** > **Internet**, toggle on **Wi-Fi**, select your network, and enter the password. > > > > > [!NOTE] > > > > > > On a terminal that has already been onboarded, the menu icon is hidden. See [Change the Wi-Fi network](/docs/checkout/in-person/terminal-troubleshooting#change-the-wi-fi-network). > > > > **5. Get settings** > > > > On the terminal > > > > Only needed if the terminal does not pick up its configuration on its own, or if its status is `ACTION_REQUIRED`. > > > > 1. Swipe **↑ Up** and **Tap the ☰ Menu icon twice** to access the menu options. > > > > 2. Go to **Innstillinger (Settings)** > **Service** > enter the **Service password** (ask Dintero for it) > **Hent Innstillinger (Get settings)**. > > > > 3. The terminal fetches the latest configuration, and automatically restarts. > > > > > [!NOTE] > > > > > > If **Get settings** is listed directly in the menu, select it there. You do not need the Service password. > [tab] API > > **1. Onboard a payout destination** > > Call the API > > The payout destination is the seller of record - the entity that receives the funds. KYC is a one-time step per legal entity. > > [`POST /accounts/{oid}/payout-destinations`](/api-reference/payout-destinations/aid_mgmnt_payout_destinations_post) > > ```http theme={null} > POST /v1/accounts/{oid}/payout-destinations > Authorization: Bearer > Content-Type: application/json > > { > "payout_destination_id": "seller-1", > "payout_reference": "My Company AS", > "organization": { > "organization_number": "923663487" > }, > "address": { > "country": "NO", > "postal_place": "Oslo", > "address_line": "Sommerkroveien 34" > }, > "bank_accounts": [ > { > "bank_account_number": "86011117947", > "bank_account_currency": "NOK" > } > ], > "form_submitter": { > "email": "contact@example.com" > } > } > ``` > > The response contains the KYC link in `links`, under `rel: contract_url`: > > ```json Response theme={null} > { > [...] > "payout_destination_id": "seller-1", > "case_status": "WAITING_FOR_DECLARATION", > "links": [ > { > "rel": "contract_url", > "href": "https://example.dintero.com/kyc/..." > } > ] > } > ``` > > Open that URL to complete the declaration form and sign the agreement. > > > [!TIP] > > > > **Ready when** `case_status` is `ACTIVE`. > > > > Use [`GET /v1/accounts/{oid}/payout-destinations/{payout_destination_id}`](/api-reference/payout-destinations/aid_mgmnt_payout_destinations_get_by_id), or subscribe to the [`approval_payout_destination_update`](/api-reference/example-management-auth-events/example_approval_payout_destination_update_event) webhook. > > **2. Create a store** > > Call the API > > A store represents a physical location. Stores are linked to one payout destination. > > [`POST /v1/accounts/{aid}/stores`](/api-reference/account-stores/aid_account_management_stores_post) > > ```http theme={null} > POST /v1/accounts/{aid}/stores > Authorization: Bearer > Content-Type: application/json > > { > "store_id": "oslo-center", > "store_name": "Oslo Center", > "organization": { > "organization_number": "923663487" > }, > "payout_destination": { > "payout_destination_id": "seller-1" > }, > "phone_number": "+4799999999" > } > ``` > > Keep **`store_id`** from the response (in this example, `oslo-center`). You need it in the next step. > > > [!TIP] > > > > **Ready when** `status` is `ACTIVE` (can take a couple of hours). > > > > Use [`GET /v1/accounts/{aid}/stores/{store_id}`](/api-reference/account-stores/aid_account_management_stores_sid_get). While the store is `PENDING` or `ERROR`, `status_reason` tells you what it is waiting on. See [Store statuses](/docs/checkout/in-person/terminal-troubleshooting#store-statuses). > > **3. Add a terminal** > > Call the API > > Each terminal is connected to a single store. > > [`POST /v1/accounts/{aid}/terminals`](/api-reference/account-terminals/aid_account_management_terminals_post) > > ```http theme={null} > POST /v1/accounts/{aid}/terminals > Authorization: Bearer > Content-Type: application/json > > { > "device_serial_number": "158222607285", > "store_id": "oslo-center" > } > ``` > > Keep **`terminal_id`** from the response. The format is your Dintero account ID (`T` prefix for sandbox, `P` for production), a hyphen, then the terminal ID. For example `T12345678-T0010`. Use it as `order.store.terminal_id` when creating a session. > > > [!TIP] > > > > **Ready when** `status` is `PENDING` or `ACTION_REQUIRED`. > > > > Use [`GET /v1/accounts/{aid}/terminals/{terminal_id}`](/api-reference/account-terminals/aid_account_management_terminals_termid_get). > > > > For what each status means, see [Terminal statuses](/docs/checkout/in-person/terminal-troubleshooting#terminal-statuses). > > The terminal is registered, but not ready to take payments yet. Continue with the physical setup below. > > **4. Connect to Wi-Fi** > > On the terminal > > 1. Turn on the terminal, swipe **↑ Up** on the display, and open the **iNfiniPay** app. The terminal installs the software and restarts. > > 2. Tap the **☰ Menu icon** in the top-right corner of the screen. > > 3. Go to **Network Settings** > **Internet**, toggle on **Wi-Fi**, select your network, and enter the password. > > > [!NOTE] > > > > On a terminal that has already been onboarded, the menu icon is hidden. See [Change the Wi-Fi network](/docs/checkout/in-person/terminal-troubleshooting#change-the-wi-fi-network). > > **5. Get settings** > > On the terminal > > Only needed if the terminal does not pick up its configuration on its own, or if its status is `ACTION_REQUIRED`. > > 1. Swipe **↑ Up** and **Tap the ☰ Menu icon twice** to access the menu options. > > 2. Go to **Innstillinger (Settings)** > **Service** > enter the **Service password** (ask Dintero for it) > **Hent Innstillinger (Get settings)**. > > 3. The terminal fetches the latest configuration, and automatically restarts. > > > [!NOTE] > > > > If **Get settings** is listed directly in the menu, select it there. You do not need the Service password. > > **6. Activate the terminal** > > Call the API > > The terminal has to be online before it can answer. > > [`POST /v1/admin/terminals/{terminal_id}/activations`](/api-reference/terminals/admin_terminals_terminal_id_activations_post) > > ```http theme={null} > POST /v1/accounts/{aid}/payments/admin/terminals/T12345678-T0010/activations > Authorization: Bearer > ``` > > The call returns immediately, and the terminal is activated in the background. > > > [!TIP] > > > > **Ready when** `status` is `ACTIVE`. > > > > Use [`GET /v1/accounts/{aid}/terminals/{terminal_id}`](/api-reference/account-terminals/aid_account_management_terminals_termid_get). > > > > If activation does not complete, the terminal returns to `ACTION_REQUIRED` with `status_reason` `START_ACTIVATION`. Check that the terminal is online and call the endpoint again. See [Terminal statuses](/docs/checkout/in-person/terminal-troubleshooting#terminal-statuses). *** ## API details > [accordion] Track KYC approval > > * **Webhook:** subscribe to `approval_payout_destination_update`. The payout destination is ready when `case_status` is `ACTIVE`. > * **Polling:** [`GET /v1/accounts/{aid}/management/settings/approvals/payout-destinations`](/api-reference/approvals/aid_management_settings_approvals_payout_destinations_get) > > For more detail on the KYC flow and reminder emails, see [Add sellers and payout destinations](/docs/checkout/split-payment/add-payout-destinations). > [accordion] Store identifiers and fields > > A store has two identifiers: > > * `store_id` - the identifier you send. Used as `order.store.id` in checkout sessions. If you omit it, Dintero generates one. > * `id` - Dintero-generated (for example `P12345678-0026`). > > When a store is linked to an active payout destination, address, phone number, and other fields are set automatically from the validated organization data, and you cannot set a custom address. > > The store's `organization.organization_number` must match the organization on the payout destination. > [accordion] Inspect a terminal > > * [`GET /v1/accounts/{aid}/terminals/{terminal_id}`](/api-reference/account-terminals/aid_account_management_terminals_termid_get) - one terminal, including its status. > * [`GET /v1/accounts/{aid}/terminals`](/api-reference/account-terminals/aid_account_management_terminals_get) - all terminals on the account. > > For what each status means, see [Terminal statuses](/docs/checkout/in-person/terminal-troubleshooting#terminal-statuses). > [accordion] Testing > > In test, use a [test bank account number](/docs/checkout/testdata/approvals/bank-accounts) (the example above uses `86011117947`), and set `payout_destination_description` to `AUTO_APPROVE` to skip the KYC flow. > > See [Auto-approve sellers](/docs/checkout/testdata/approvals/auto-approve). ## Next steps With the payout destination, store, and terminal in place, you can now [Create a terminal session](/docs/checkout/in-person/creating-terminal-session). # Manage terminals remotely Source: https://docs.dintero.com/docs/checkout/in-person/terminal-operations Send administrative commands to a Dintero payment terminal and read the results, including end-of-day, log upload, update checks, opening the terminal menu, pinging the terminal, and printing. Terminal operations let you send administrative commands to a registered payment terminal and read the results. Use them to run an end-of-day close, ask the terminal to upload its logs, check for software updates, open the terminal menu, ping the terminal to see whether it is reachable, or print on the terminal's printer, without physically touching the device. Operations are asynchronous. You send a command, the API dispatches it to the terminal and returns immediately with a `PENDING` operation, and the terminal processes the command in the background. You then poll the operation to see how it finished. > [!NOTE] > > Terminal operations are administrative commands. They do not start a payment. To take a payment on a terminal, see [creating a terminal session](/docs/checkout/in-person/creating-terminal-session). ## Available operations | Operation | What it does | Use it when | Terminal status required | | - | - | - | - | | `end_of_day` | Closes the terminal's current batch and settles it with the acquirer, then reports the batch totals. | Once per trading day, after the last payment. | `ACTIVE` | | `send_logs` | Has the terminal upload its log files to the terminal vendor. The logs are not returned through the API. | Support asks for logs while investigating a problem with the device. | `ACTIVE` | | `check_update` | Has the terminal check for a software update and install one if available. May reboot the terminal. | A terminal is behind on software, or support asks you to update it. | `ACTIVE` | | `open_menu` | Opens the settings menu on the terminal's own screen, for an operator standing at the device. The terminal cannot take payments while the menu is open. | Someone at the terminal needs to change its configuration. | Any status except `PENDING` | | `poll_terminal` | Pings the terminal to see whether it is online and responding. No effect on the device. | Before sending another operation, or when a terminal is reported as unresponsive. | Any status | | `print_text` | Prints lines of text you send on the terminal's printer. Dintero does not compose or check the content. | Your cash register system uses the terminal as its printer, for example for a sales receipt. | `ACTIVE` | | `print_receipt` | Prints a copy of the payment receipt of an in-person transaction, marked as a copy. | A customer or the merchant needs the payment receipt again. | `ACTIVE` | If the terminal's status does not allow the operation, the API responds with `400 Bad Request`. `poll_terminal` is never rejected on status, so it is the safe way to check a terminal you are unsure about. ## Send a command ```http theme={null} POST https://api.dintero.com/v1/accounts/{account_id}/payments/admin/terminals/operations Authorization: Bearer Content-Type: application/json ``` The request body identifies the terminal and the operation to run. ```json theme={null} { "terminal_id": "P12345678-T0012", "operation": "end_of_day" } ``` The response is returned as soon as the command is dispatched to the terminal. The terminal's response is processed asynchronously, so the operation starts with status `PENDING`. ```json theme={null} { "id": "3f1a9c2e-8b7d-4f6a-9c1e-2d5b8a0f4e6c", "terminal_id": "P12345678-T0012", "operation": "end_of_day", "status": "PENDING", "created_at": "2026-06-29T09:00:00Z", "created_by": "user@example.com", "updated_at": "2026-06-29T09:00:00Z", "updated_by": "user@example.com" } ``` See [POST /admin/terminals/operations](/api-reference/terminals/admin_terminals_operations_post) for the full schema. ### Idempotency Pass an `Idempotency-Key` header to ensure the same command is only executed once, for example when retrying after a network error. ```http theme={null} Idempotency-Key: 9b2c5d7e-1a3f-4c6b-8d9e-0f1a2b3c4d5e ``` ### Check that a terminal is reachable The `poll_terminal` operation pings the terminal without changing anything on the device. Use it to confirm that a terminal is online and responding, for example before you send another operation or when you are investigating a terminal that customers report as unresponsive. ```json theme={null} { "terminal_id": "P12345678-T0012", "operation": "poll_terminal" } ``` `poll_terminal` can be sent regardless of the terminal's status, so you can also use it on a terminal that is not `ACTIVE`. The operation ends as `COMPLETED` when the terminal answers, and as `TIMEOUT` when no answer arrives within the timeout window. ### Print text `print_text` prints the lines you send, in order. Each line has its own `size` and `align`. ```json theme={null} { "terminal_id": "P12345678-T0012", "operation": "print_text", "parameters": { "lines": [ { "text": "Dintero Butikk AS", "size": "small", "align": "center" }, { "text": " ", "size": "small", "align": "left" }, { "text": "Total kr 10,00", "size": "large", "align": "left" } ] } } ``` * Send 1 to 255 lines. Each `text` is at most 255 bytes. * The terminal does not wrap lines. A line that is too wide is cut off at the right edge. A line fits 29 characters at `small` and `medium`, and 15 at `large`. * A `large` line overlaps a `small` or `medium` line right above it. Put a blank line before a `large` line. * For a blank line, send `" "`. An empty `text` is rejected with `400`. * A tab or a newline in `text` prints as a space. Send each printed line as its own entry in `lines`. ### Print a copy of a payment receipt `print_receipt` prints the receipt text the terminal wrote during the payment, marked as a copy. Dintero does not compose a receipt itself. ```json theme={null} { "terminal_id": "P12345678-T0012", "operation": "print_receipt", "parameters": { "transaction_id": "P12345678.465UfBENeLpkBvwmqfTC4k", "type": "customer" } } ``` * `type` is `customer` for the cardholder's copy, or `merchant` for the merchant's copy. * When no receipt text is stored for the transaction, for example for older transactions, the API responds with `400`. ### One operation of each type at a time A terminal has at most one pending operation of each type. If an operation of the same type is already pending for the terminal, the API responds with `409 Conflict` and a `Retry-After` header indicating how many seconds to wait before retrying. Operations of other types are not blocked: a pending `end_of_day` does not block a `print_text`. ## List operation results Poll operations to see how a command finished. The endpoint returns operations and supports filtering by `terminal_id` and `operation_id`. ```http theme={null} GET https://api.dintero.com/v1/accounts/{account_id}/payments/admin/terminals/operations?terminal_id=P12345678-T0012 Authorization: Bearer ``` To check a single operation, filter by the `id` returned when you sent the command. ```http theme={null} GET https://api.dintero.com/v1/accounts/{account_id}/payments/admin/terminals/operations?operation_id=3f1a9c2e-8b7d-4f6a-9c1e-2d5b8a0f4e6c Authorization: Bearer ``` Operations are returned most recently created first. Use `limit` (default 100\) and `starting_after` with the `id` of the last operation you saw to page through older ones. See [GET /admin/terminals/operations](/api-reference/terminals/admin_terminals_operations_get) for the full schema. ### Operation status | Status | Meaning | | - | - | | `PENDING` | The operation has been dispatched to the terminal and is awaiting a response. | | `COMPLETED` | The terminal responded and the operation finished successfully. | | `FAILED` | The terminal responded but reported a failure. | | `TIMEOUT` | No response was received from the terminal within the timeout window. A new operation can be dispatched. | Which of these an operation can reach depends on the operation. `open_menu` and `poll_terminal` are never `FAILED` - the terminal does not report a failure for them, so an unreachable terminal ends the operation as `TIMEOUT`. `end_of_day`, `send_logs`, `check_update`, `print_text` and `print_receipt` are `FAILED` when the terminal answers but reports a problem, and the `result` says what it was. ### Operation result An operation that reaches `COMPLETED` or `FAILED` carries a `result` object whose contents depend on the operation - on `FAILED` it is what tells you why. A `TIMEOUT` operation never has a `result`. The examples below show only that field of the operation. > [!NOTE] > > The fields inside `result` are camelCase, unlike the rest of the operation. > The `end_of_day` counts and amounts are the strings the terminal reported, > not numbers, and are only present when the terminal included them. `poll_terminal` and `open_menu` report only that the terminal answered: ```json theme={null} { "result": { "result": "ok" } } ``` `send_logs` reports whether the terminal reached the log destination. `connectionError` means it did not, and the operation is `FAILED`: ```json theme={null} { "result": { "result": "connectionError" } } ``` `check_update` adds whether the terminal will reboot to apply an update. When `terminalReboot` is true, the terminal is unavailable for payments until it is back online - use `poll_terminal` to see when it is reachable again: ```json theme={null} { "result": { "result": "ok", "terminalReboot": true } } ``` `print_text` and `print_receipt` report whether the terminal printed: ```json theme={null} { "result": { "result": "unknown_error" } } ``` | `result` | Meaning | | - | - | | `ok` | The terminal printed. | | `out_of_paper` | The terminal reported that it is out of paper. The operation is `FAILED`. | | `no_printer` | The terminal has no printer. The operation is `FAILED`. | | `unknown_error` | The terminal reported a failure without a reason, for example missing paper. The operation is `FAILED`. Check the printer before you retry. | `end_of_day` reports the outcome and the batch totals: ```json theme={null} { "result": { "result": "accepted", "batchId": "42", "startOfDay": "2026-06-29T06:00:00Z", "lastEndOfDay": "2026-06-28T22:00:04Z", "purchasesCount": "37", "purchasesAmount": "1284500", "reversalsCount": "1", "reversalsAmount": "9900", "saleAmount": "1274600", "tipAmount": "12000" } } ``` | `result` | Meaning | | - | - | | `accepted` | The batch was closed and settled. | | `offline_accepted` | The terminal closed the batch without reaching the acquirer. It settles when the terminal is back online. | | `not_accepted` | The acquirer rejected the batch. The operation is `FAILED`. | | `no_user_found` | No operator matched the `operator_id` you passed, so nothing was closed. The operation is `FAILED`. | | `unknown` | The terminal's response omitted the outcome. The operation is `FAILED` and the batch state is undetermined - check the terminal before retrying. | ## End-of-day when a terminal is removed Removing a terminal with [`DELETE /v1/accounts/{aid}/terminals/{terminal_id}`](/api-reference/account-terminals/aid_account_management_terminals_termid_delete) also starts an `end_of_day` operation on it, to close the terminal's open batch. The operation runs asynchronously and does not block or fail the removal. Read its result from the operations list filtered by the removed terminal's `terminal_id`, as described in [List operation results](#list-operation-results). A terminal that is turned off or unreachable when it is removed ends the operation as `TIMEOUT`. No operation is created for a terminal that is not active, for example one still being activated. ## Scopes | Endpoint | Scopes | | - | - | | `POST /accounts/{account_id}/payments/admin/terminals/operations` | `admin:checkout` or `write:checkout:/admin/terminals` | | `GET /accounts/{account_id}/payments/admin/terminals/operations` | `admin:checkout` or `read:checkout:/admin/terminals` | # Troubleshooting your terminal Source: https://docs.dintero.com/docs/checkout/in-person/terminal-troubleshooting Troubleshoot common issues with Dintero terminals, including provisioning errors and network problems. # Terminal statuses > [tab] Backoffice > > Backoffice shows the status of each terminal in **In-person payments** > **Terminals**. > > | Status | Meaning | How it got there | Action | > | - | - | - | - | > | **Pending** | The terminal has been registered and is waiting to be provisioned. | You added the terminal, or an activation attempt is under way. | None. The status updates automatically. | > | **Activate terminal** | The terminal needs to fetch its configuration before it can be activated. Backoffice replaces the status with this button. | Dintero finished provisioning, or a configuration fetch was attempted and did not complete. | Click **Activate terminal** and follow the on-screen instructions. See [terminal onboarding](/docs/checkout/in-person/terminal-onboarding). | > | **Activated** | The terminal is provisioned and ready to accept payments. | The terminal fetched its configuration and confirmed it. | None. | > | **Inactive** | The device has been disabled and cannot take payments. | The device was disabled on the Dintero side. | Contact Dintero support. Re-enabling is not self-service. | > | **Deleted** | The terminal has been removed from the account. | You deleted the terminal. | None. Add the terminal again to reuse it. | > > If setting up the terminal failed and it does not reach **Activated**, delete the terminal and add it again, or contact Dintero support. > [tab] API > > Check the current status with [`GET /v1/accounts/{aid}/terminals/{terminal_id}`](/api-reference/account-terminals/aid_account_management_terminals_termid_get). > > | Status | Meaning | How it got there | Action | > | - | - | - | - | > | `PENDING` | The terminal has been registered and is waiting to be provisioned. | You registered the terminal, or an activation attempt is under way. | None. The status updates automatically. | > | `ACTION_REQUIRED` | The terminal is ready to be activated. `status_reason` is `START_ACTIVATION`. | Dintero finished provisioning, or an activation attempt did not complete. | Make sure the terminal is online, then call [`POST /v1/admin/terminals/{terminal_id}/activations`](/api-reference/terminals/admin_terminals_terminal_id_activations_post). See [terminal onboarding](/docs/checkout/in-person/terminal-onboarding). | > | `ACTIVE` | The terminal is provisioned and ready to accept payments. | The terminal fetched its configuration and confirmed it. | None. | > | `INACTIVE` | The device has been disabled and cannot take payments. | The device was disabled on the Dintero side. | Contact Dintero support. Re-enabling is not self-service. | > | `ERROR` | Provisioning failed. | Something went wrong during setup that did not recover on its own. | Delete the terminal and register it again, or contact Dintero support. | > | `DELETED` | The terminal has been removed from the account. | You deleted the terminal. | None. Register the terminal again to reuse it. | > [!WARNING] > > Only an `ACTIVE` terminal can take a payment. If `seitatech.in_person` is the only enabled payment method, creating a session against a terminal in any other status fails with `order.store.terminal_id: terminal is not active`. > > If other payment methods are enabled, the session is created but `seitatech.in_person` is disabled instead. See [The terminal does not prompt the customer](#the-terminal-does-not-prompt-the-customer). Most [terminal operations](/docs/checkout/in-person/terminal-operations) are restricted by status too - `poll_terminal` is the only one you can always send. ## Check whether a terminal is reachable The terminal status tells you how far the terminal got through provisioning, not whether it is online right now. To check that, send a [`poll_terminal` operation](/docs/checkout/in-person/terminal-operations#check-that-a-terminal-is-reachable). It pings the terminal without changing anything on the device, and can be sent no matter which status the terminal has. # Store statuses A store must be `ACTIVE` before its terminals can take payments. When a store is `PENDING` or `ERROR`, [`GET /v1/accounts/{aid}/stores/{store_id}`](/api-reference/account-stores/aid_account_management_stores_sid_get) returns a `status_reason` that tells you what the store is waiting on. `status_reason` is not set for other statuses, and new values may be added. | `status_reason` | Meaning | Action | | - | - | - | | `WAITING_FOR_PAYOUT_DESTINATION` | The payout destination is missing or not `ACTIVE`. | Complete KYC for the payout destination. See [Add sellers and payout destinations](/docs/checkout/split-payment/add-payout-destinations). | | `ENROLLMENT_NOT_STARTED` | The payout destination is `ACTIVE` and the enrollment is not sent yet. | None. The status updates automatically. | | `WAITING_FOR_ENROLLMENT` | The enrollment is sent and there is no answer yet. | None. The status updates automatically. | | `ENROLLMENT_REJECTED` | The enrollment was rejected. The store has status `ERROR`. | Contact Dintero support. | # Session issues ## The terminal does not prompt the customer > [!NOTE] > > This only applies when the payment profile or session enables Card (Present) (`seitatech.in_person`) alongside online payment methods. If Card (Present) is the only payment method, an invalid in-person request fails with a validation error. When Card (Present) is combined with online payment methods, an invalid in-person request does not fail. The session is created with `seitatech.in_person` disabled, so the online payment methods keep working. The terminal is not prompted, and no error is returned. Validation fails when: * `order.store.id`, `order.store.terminal_id`, or `order.store.payout_destination_id` is missing. * The terminal in `order.store.terminal_id` is not active or not found. To find out why in-person was disabled, retrieve the session with [GET /sessions/\{session_id}](/api-reference/session/checkout_session_get) and check `configuration.seitatech.in_person.payability_disabled_reasons`: ```json Response theme={null} { "configuration": { "seitatech": { "type": "payment_type", "in_person": { "type": "payment_product_type", "enabled": false, "payability": "disabled_by_validation", "payability_disabled_reasons": [ { "code": "missing_store_id", "message": "order.store.id: must be set when seitatech.in_person is enabled" } ] } } } } ``` > [!WARNING] > > If the terminal does not prompt the customer after you create the session, check `payability_disabled_reasons` before you retry. # Terminal tasks These tasks are done on the physical terminal, on a terminal that already has been onboarded. ## Service password The Service menu asks for a password. It is a rotating code you can request from Dintero support. If **Network settings** and **Get settings** are listed directly in the terminal menu, open them there. You do not need the Service password. Otherwise, open them under **Service**, as described in the steps below. ## Change the Wi-Fi network Use this when moving a terminal to a new location or replacing the network. 1. Swipe **↑ Up** and **Tap the ☰ Menu icon twice** to access the menu options. 2. Go to **Innstillinger (Settings)** > **Service** > enter the **Service password** > **Nettverksinnstilling (Network & internet)**. 3. Select your Wi-Fi network and enter the password. ## Fetch the terminal settings Use this when the status is `ACTION_REQUIRED`. The terminal has not pulled its configuration yet. 1. Make sure the terminal is on a Wi-Fi network. See [Change the Wi-Fi network](#change-the-wi-fi-network). 2. Swipe **↑ Up** and **Tap the ☰ Menu icon twice** to access the menu options 3. Go to **Innstillinger (Settings)** > **Service** > enter the **service password** > **Hent Innstillinger (Get settings)**. 4. The terminal fetches the latest configuration, and automatically restarts. # Payments Source: https://docs.dintero.com/docs/checkout/index Accept payments online with Dintero Checkout and in person with payment terminals. Support cards, Vipps, Klarna, invoices, Apple Pay, Google Pay, and more. Get to market faster and convert more customers. Instead of building and maintaining payment UI, handling PCI compliance, or integrating payment providers one by one, you get a single hosted checkout that works across web, mobile, and in-person. Optimized for conversion and ready from day one. You create a session with your order details, Dintero presents the right payment options to your customer, and you receive a callback when the payment completes. From there, you manage the full lifecycle: capture, refund, and void, through the same API. ## Quickstart > [card] [Quickstart your first checkout](/docs/checkout/quickstart) > > Create credentials, authenticate, build a checkout session, and handle the payment result. ## Common use cases > [card] [Accept payments online](/docs/checkout/use-cases/online-checkout) > > Integrate Dintero Checkout to your website or app. > [card] [Fast-track returning customers](/docs/checkout/use-cases/express-checkout) > > Use Dintero Express for frictionless, repeat purchases. > [card] [Set up recurring payments](/docs/checkout/use-cases/subscriptions) > > Tokenize cards and bill customers on a schedule. > [card] [Send payment links](/docs/checkout/use-cases/payment-links) > > Deliver checkout links via SMS or email. > [card] [Split payments across sellers](/docs/checkout/use-cases/marketplace-split-payments) > > Distribute funds to multiple sellers on your platform. > [card] [Accept payments in person](/docs/checkout/use-cases/in-person-payments) > > Charge customers on physical payment terminals. # Klarna EMD attachments Source: https://docs.dintero.com/docs/checkout/klarna-emd Send extra merchant data (EMD) to Klarna with Dintero Checkout sessions for travel, events, marketplaces, and digital goods to improve order acceptance. Based on the business category you operate in and what goods you sell, you might need to provide additional information about the order items when creating or updating a session. > [!NOTE] > > This is only applicable if you have Klarna as an enabled payment method in your checkout configuration. ## EMD In some cases, Klarna requires additional information regarding the transaction in order to make a correct risk assessment. This information is called [Extra Merchant Data (EMD)](https://docs.klarna.com/klarna-checkout/popular-use-cases/extra-merchant-data/) and may consist of data about the customer performing the transaction, the product/services associated with the transaction, or the seller and their affiliates. The type of information you need to provide is determined by the business category you operate in and what you sell and can be categorized into what Klarna calls "EMD packages". The various packages, short descriptions of each package, and examples of what can be contained in them, are shown in the table below: ### EMD packages and descriptions | EMD package | Description | Example | | - | - | - | | Event sales orders | Event tickets | Concert tickets | | Recurring payment transactions | Subscriptions or recurring payments | Contact lens subscription | | Marketplace orders | Orders that are being sold on a marketplace | Sub-merchants sell goods through your marketplace | | Travel-related transactions | Travel tickets | Flight tickets | ## An example selling concert tickets Travis Scott is coming to Oslo. He is going to light up Oslo Spektrum. Everyone you know is excited, but you are stressed because you work at Ticket Provider AS and have been tasked with creating a system that sells the tickets to the concert. But fear not, Dintero to the rescue! Since you are very smart and appreciate easy and robust payments, you are already using Dintero as your trusted payment provider. You also have Klarna enabled because Klarna is cool and people want to pay using Klarna. We just need some extra information from you regarding the concert. Referring to the table above, since you are selling tickets to a concert and have Klarna as an enabled payment option, you need to provide the information that is described in the *Event sales orders* EMD package. Since you could theoretically be selling a ticket that contains multiple events as part of a package, you need to provide the event related information as an array of objects, with each of the objects containing the required information related to the event. In your case, you are only selling concert tickets to a single concert, so we only need an array of length 1 with one event object. What needs to be included in this object and what the property values could be in your case is shown below: ```js theme={null} emd: { event: [ { event_name: "Travis Scott Oslo Spektrum 2023", event_company: "Ticket Provider AS", genre_of_event: "Rap", start_time: "2023-11-11T20:00:00Z", end_time: "2023-11-11T22:00:00Z", ticket_delivery_method: "email", ticket_delivery_recipient: "customer@mail.com" } ] } ``` You can also choose to include this information, but it is not required: ```js theme={null} arena_name: "Oslo Spektrum", arena_location: { city: "Oslo", country: "NO", street_address: "Sonja Henies plass 2", postal_code: "0185" }, access_controlled_venue: true, affiliate_name: "Affiliate" ``` The `emd` property should be placed either on the order items or directly on the order when [creating a session]. To learn more about the `emd` property and what should be included for the different packages, please refer to the [API docs for creating a session]. That's it! All done. Now you can kick back and relax and perhaps even buy a ticket to the concert yourself. [creating a session]: /docs/checkout/create-session [API docs for creating a session]: /api-reference/session/checkout_session_profile_post # Customer checkout with Kravia Source: https://docs.dintero.com/docs/checkout/kravia/checkout Offer Kravia invoice payments in Dintero Checkout: collect billing details, run identity verification, and let Kravia deliver and collect the invoice. Use this flow when customers select invoice payment during checkout. The customer provides their billing details, completes identity verification if required, and invoice delivery and collection are handled automatically. ## How it works ```mermaid theme={null} sequenceDiagram participant Customer participant Dintero participant Kravia Customer->>Dintero: Selects Kravia invoice Dintero->>Customer: Collects billing address alt Identity verification required Dintero->>Customer: Redirect to BankID Customer->>Dintero: Completes verification end Dintero->>Kravia: Create invoice Kravia-->>Dintero: Invoice created + PDF URL Dintero-->>Merchant: Transaction AUTHORIZED Note over Dintero: INITIATE_CAPTURE event added
(Kravia begins delivery) Kravia->>Customer: Delivers invoice Customer->>Kravia: Pays invoice Kravia-->>Dintero: Payment confirmed Dintero-->>Merchant: Transaction CAPTURED Note over Dintero: settlement_status updates to SETTLED
when funds reach merchant ``` ## Step-by-step implementation ### 1. Configure payment types Enable the payment types you need in your payment profile or session configuration: ```json theme={null} { "configuration": { "kravia": { "type": "payment_type", "invoice_b2b": { "type": "payment_product_type", "enabled": true, "days_until_due": 14 }, "invoice_b2b_grouped": { "type": "payment_product_type", "enabled": true, "days_until_due": 14, "invoice_schedule": { "interval": "monthly" } }, "invoice_b2c": { "type": "payment_product_type", "enabled": true, "days_until_due": 14 } } } } ``` ### 2. Create checkout session ```http theme={null} POST /v1/sessions-profile Authorization: Bearer Content-Type: application/json { "url": { "return_url": "https://example.com/accept", "callback_url": "https://example.com/callback" }, "order": { "amount": 50000, "currency": "NOK", "vat_amount": 10000, "merchant_reference": "order-123", "items": [ { "amount": 50000, "quantity": 1, "line_id": "1", "description": "Consulting services", "vat": 25, "id": "item-1" } ] }, "configuration": { "kravia": { "type": "payment_type", "invoice_b2b": { "type": "payment_product_type", "enabled": true, "days_until_due": 14 } } } } ``` ### 3. Customer completes checkout The customer: 1. Selects "Invoice" as payment method 2. Enters billing address (see [Billing Address Requirements](#billing-address-requirements)) 3. Completes BankID verification (if required) 4. Invoice is created and Kravia begins delivery to the customer ### 4. Receive transaction After invoice creation, you receive a transaction with status `AUTHORIZED`. An `INITIATE_CAPTURE` event is added automatically to mark the start of Kravia's delivery and collection. The status remains `AUTHORIZED` until the shopper pays the invoice. ```json theme={null} { "id": "T12345", "status": "AUTHORIZED", "payment_product_type": "kravia.invoice_b2b", "metadata": { "kravia:invoice_number": "A1B2C-000001", "kravia:invoice_url": "https://checkout.dintero.com/transaction-attachments/..." }, "events": [ { "event": "AUTHORIZE", "metadata": { "kravia:invoice_date": "2026-01-15", "kravia:invoice_due_date": "2026-01-29", "kravia:invoice_number": "A1B2C-000001", "kravia:creditor_id": "12345", "kravia:invoice_id": "98765" } }, { "event": "INITIATE_CAPTURE" } ] } ``` When Kravia confirms the shopper has paid, the transaction transitions to `CAPTURED` (or `PARTIALLY_CAPTURED` for partial payment) and a `CAPTURE` event is appended. See [Transaction management](/docs/checkout/transaction-management) for the shared lifecycle and event model. > [!NOTE] > > The PDF may take a moment to become available. Retrieve the transaction again if `kravia:invoice_url` is missing from its metadata. ## Configuration options | Option | Applies To | Type | Default | Description | | - | - | - | - | - | | `enabled` | All | Boolean | `false` | Enable this payment type | | `days_until_due` | All | Integer (0-365) | 14 | Days until invoice is due. Use at least 3 days. | | `require_identity_verification` | All | Boolean | `true` | Require BankID verification | | `invoice_schedule.interval` | B2B Grouped | String | `"monthly"` | Billing cycle: `"monthly"` or `"quarterly"` | | `invoice_channel` | B2B, B2C | String | `"kravia"` | `"kravia"` for automatic delivery, `"merchant"` for [merchant delivery](/docs/checkout/kravia/invoice-delivery) | ## Identity verification Identity verification is required by default for all payment types and uses BankID. To disable it, set `require_identity_verification: false` on the payment type configuration. ## Transaction lifecycle In the standard checkout flow, the transaction is `AUTHORIZED` when the invoice is created and an `INITIATE_CAPTURE` event is added as Kravia begins delivery. The transaction moves to `CAPTURED` once Kravia confirms the shopper has paid the invoice in full, or to `PARTIALLY_CAPTURED` for partial payment. See the [transaction lifecycle](/docs/checkout/kravia/overview#transaction-lifecycle) in the overview for the full state diagram, and [Transaction management](/docs/checkout/transaction-management) for the shared capture/void/refund operations. ## Cancellations Refund is not supported for Kravia. To cancel an invoice, use [`POST /v1/transactions/{id}/void`](/docs/checkout/transaction-management#void-cancel): ```http theme={null} POST /v1/transactions/{transaction_id}/void Authorization: Bearer ``` | Transaction status | Effect of void | | - | - | | `AUTHORIZED` | Cancels the invoice with Kravia. Status changes to `AUTHORIZATION_VOIDED`. | | `PARTIALLY_CAPTURED` | Cancels the remaining unpaid amount with Kravia. Funds already in transit from the shopper are automatically refunded by Kravia. | | `CAPTURED` | Not allowed. The shopper has already paid in full. | > [!WARNING] > > * **Grouped invoices:** Cancel purchases before the end of the configured billing period (month or quarter). After that, cancellation may no longer be possible. > * **Refunds:** The `/refund` operation is not supported for Kravia transactions. If the shopper overpays an invoice, Kravia automatically refunds the difference. No merchant action is needed. ## Billing address requirements ### B2C invoices Required fields: `first_name`, `last_name`, `address_line`, `postal_code`, `country` (ISO 3166 alpha-2). `phone_number` and `email` are optional. ### B2B invoices Required fields: `business_name`, `organization_number`, `address_line`, `postal_code`, `country` (ISO 3166 alpha-2). `first_name`, `last_name`, `phone_number`, and `email` are optional. You can also provide a `customer_reference`, for example a department or project name. Use it to [group purchases into separate invoices](/docs/checkout/kravia/grouped-invoices#customer-grouping) within the same company. > [!NOTE] > > Organization numbers: Norway uses 9 digits, Sweden uses 10 or 12 digits. ### Name on the invoice Kravia accepts at most 50 characters for the name on the invoice. To keep long names within this limit, Dintero may shorten the name it sends to Kravia: * **Companies**: Dintero removes company form suffixes and shortens the organization name. * **Persons**: Dintero uses the first name and the first letter of the last name. Names of 50 characters or fewer are sent unchanged. For longer names, the name on the delivered invoice differs from the name in the session. ## Invoice dates ### Standard invoices (B2B and B2C) * **Issue date**: transaction date * **Due date**: issue date + `days_until_due` (default: 14 days) ### Grouped invoices (B2B grouped) For grouped invoices, multiple purchases are consolidated into a single invoice per billing period. See [Grouped Invoices](/docs/checkout/kravia/grouped-invoices) for schedule details, customer grouping logic, and configuration. ## See also * [Merchant Initiated](/docs/checkout/kravia/merchant-initiated-payments): create and pay invoices without customer interaction * [Invoice Delivery](/docs/checkout/kravia/invoice-delivery): control who delivers the invoice * [Testing](/docs/checkout/testdata/other/checkout-kravia-testdata): test individual and grouped invoice payment scenarios # Grouped invoices (B2B) with Kravia Source: https://docs.dintero.com/docs/checkout/kravia/grouped-invoices Consolidate multiple B2B purchases from the same customer into one Kravia invoice per billing period using kravia.invoice_b2b_grouped in Dintero Checkout. Grouped invoicing consolidates multiple purchases from the same customer into a single invoice per billing period. Instead of receiving an invoice for each transaction, the customer gets one combined invoice at the end of the month or quarter. ## How it works ```mermaid theme={null} sequenceDiagram participant Customer participant Dintero participant Kravia Customer->>Dintero: Purchase 1 (Jan 5) Dintero-->>Merchant: Transaction AUTHORIZED Customer->>Dintero: Purchase 2 (Jan 20) Dintero-->>Merchant: Transaction AUTHORIZED Note over Kravia: Billing period ends (Jan 31) Kravia->>Customer: Combined invoice (Feb 1) Customer->>Kravia: Pays invoice Kravia-->>Dintero: Payment confirmed Dintero-->>Merchant: Transactions CAPTURED ``` Each purchase creates its own transaction with status `AUTHORIZED`. At the end of the billing period, Kravia consolidates eligible purchases into one invoice per [customer group](#customer-grouping). When the shopper pays the consolidated invoice, the underlying transactions move to `CAPTURED` (or `PARTIALLY_CAPTURED` for partial payment). To cancel an unpaid purchase before billing, void the transaction. See [Cancellations](/docs/checkout/kravia/checkout#cancellations). ## Configuration Enable `invoice_b2b_grouped` and set the billing interval: ```json theme={null} { "configuration": { "kravia": { "type": "payment_type", "invoice_b2b_grouped": { "type": "payment_product_type", "enabled": true, "days_until_due": 14, "invoice_schedule": { "interval": "monthly" } } } } } ``` | Option | Type | Default | Description | | - | - | - | - | | `enabled` | Boolean | `false` | Enable grouped invoicing | | `days_until_due` | Integer (0-365) | 14 | Days until the consolidated invoice is due. Use at least 3 days. | | `invoice_schedule.interval` | String | `"monthly"` | `"monthly"` or `"quarterly"` | | `require_identity_verification` | Boolean | `true` | Require BankID verification | ## Invoice schedule Invoices are issued on the first weekday after the billing period ends. **Monthly**, first weekday of following month: | Purchase Date | Invoice Issue Date | Due Date | | - | - | - | | January 5th | February 1st | February 15th | | January 20th | February 1st | February 15th | | February 15th | March 1st | March 15th | **Quarterly**, first weekday of following quarter: | Purchase Date | Invoice Issue Date | Due Date | | - | - | - | | January 15th | April 1st | April 15th | | February 20th | April 1st | April 15th | | April 10th | July 1st | July 15th | Quarters: Q1 (Jan-Mar), Q2 (Apr-Jun), Q3 (Jul-Sep), Q4 (Oct-Dec) If the 1st falls on a weekend, the invoice is issued on the following Monday. Public holidays do not move the scheduled invoice date. ## Customer grouping Purchases from the same company are grouped into one invoice per billing period. Provide the company's `business_name`, `organization_number`, and `country` consistently across purchases. Use `billing_address.customer_reference` to create separate invoices for departments, projects, or other receiving units within a company. References group purchases within the same company. Different companies are always invoiced separately. For example, for purchases made by Nordmann AS in the same billing period: | Customer reference | Grouping | | - | - | | `dept-engineering` | One invoice for engineering purchases | | `dept-sales` | A separate invoice for sales purchases | | Omitted or blank | One invoice for purchases without a reference | Choose a reference the customer will recognize, and reuse it for purchases that belong together. The maximum length is 30 characters. If you omit it, Dintero uses the country and organization number, such as `NO-123456789`, as the group reference. ```json theme={null} { "billing_address": { "first_name": "Ola", "last_name": "Nordmann", "business_name": "Nordmann AS", "organization_number": "123456789", "customer_reference": "dept-engineering", "email": "ola@nordmann.no", "phone_number": "+4799999999", "address_line": "Storgata 1", "postal_code": "0151", "postal_place": "Oslo", "country": "NO" } } ``` ## Billing address Grouped invoices use the same B2B billing address fields as [standard B2B invoices](/docs/checkout/kravia/checkout#billing-address-requirements), plus the optional `customer_reference` for grouping. ## Integration Grouped invoices work with both integration approaches: * **[Customer Checkout](/docs/checkout/kravia/checkout)**: enable `configuration.kravia.invoice_b2b_grouped` in your session configuration * **[Merchant Initiated](/docs/checkout/kravia/merchant-initiated-payments#two-step-create-session-then-pay)**: use the two-step flow. Create a session with grouped invoicing enabled, then pay it with `payment_product_type: "kravia.invoice_b2b_grouped"`. ## See also * [Customer Checkout](/docs/checkout/kravia/checkout): configuration options, identity verification, and billing address details * [Merchant Initiated](/docs/checkout/kravia/merchant-initiated-payments): create and pay invoices without customer interaction * [Invoice Delivery](/docs/checkout/kravia/invoice-delivery): control who delivers the invoice * [Testing](/docs/checkout/testdata/other/checkout-kravia-testdata): test individual and grouped invoice payment scenarios # Kravia invoice delivery Source: https://docs.dintero.com/docs/checkout/kravia/invoice-delivery Override default Kravia invoice delivery by setting invoice_channel to merchant, giving you control over channel, timing, and branding for outgoing invoices. By default, invoices are delivered to your customers automatically. You can instead choose to deliver invoices yourself by setting `invoice_channel: "merchant"`. This gives you control over the delivery method, timing, and branding. It works with both [customer checkout](/docs/checkout/kravia/checkout) and [merchant initiated](/docs/checkout/kravia/merchant-initiated-payments). > [!WARNING] > > You need to request access to merchant delivery from support. This feature is not available for grouped invoices. ## How it works ```mermaid theme={null} sequenceDiagram participant Customer participant Merchant participant Dintero participant Kravia alt Customer Checkout Customer->>Dintero: Selects invoice payment else Merchant Initiated Merchant->>Dintero: POST /v1/sessions/pay end Dintero->>Kravia: Create invoice (custom distribution) Kravia-->>Dintero: Invoice created + PDF URL Dintero-->>Merchant: Transaction AUTHORIZED Merchant->>Dintero: POST /v1/transactions/{id}/capture Note over Dintero: Status stays AUTHORIZED
INITIATE_CAPTURE event added
Payment details added alt Send generated invoice Merchant->>Customer: Send PDF URL else Generate own invoice Merchant->>Merchant: Generate invoice document Merchant->>Customer: Send invoice with payment details end Customer->>Kravia: Pays invoice Kravia-->>Dintero: Payment confirmed Dintero-->>Merchant: Transaction CAPTURED Note over Dintero: settlement_status updates to SETTLED
when funds reach merchant ``` > [!WARNING] > > Before delivering the invoice to the customer, you must call `POST /v1/transactions/{id}/capture` to start collection. The transaction status remains `AUTHORIZED`; an `INITIATE_CAPTURE` event is added to mark that collection has begun. Without this, Kravia will not start collection. If `configuration.auto_capture` is `true`, collection starts immediately, so distribution of the invoice should be done promptly. ## Configuration Set `invoice_channel: "merchant"` to enable custom distribution. ### Session-level configuration (Customer checkout) ```http theme={null} POST /v1/sessions-profile Authorization: Bearer Content-Type: application/json { "url": { "return_url": "https://example.com/accept", "callback_url": "https://example.com/callback" }, "order": { "amount": 50000, "currency": "NOK", "merchant_reference": "order-123", "items": [ ... ] }, "configuration": { "kravia": { "type": "payment_type", "invoice_b2b": { "type": "payment_product_type", "enabled": true, "days_until_due": 14, "invoice_channel": "merchant" } } } } ``` ### Payment-level configuration (merchant initiated) ```http theme={null} POST /v1/sessions/pay Authorization: Bearer Content-Type: application/json { "payment": { "payment_product_type": "kravia.invoice_b2b", "operation": "invoice_payment", "days_until_due": 14, "invoice_channel": "merchant" }, "session": { "url": { "callback_url": "https://example.com/callback" }, "order": { "amount": 50000, "currency": "NOK", "merchant_reference": "inv-2026-001", "billing_address": { ... } } } } ``` ### Configuration precedence The value is resolved in this order: 1. **Session/payment configuration** (highest priority) 2. **Checkout payment options** (fallback) 3. **Default**: `"kravia"` ## Delivering the invoice After the transaction is `AUTHORIZED`, the Kravia invoice has been created and is ready for delivery. Before you deliver it through your own channel, capture the transaction to start collection with Kravia. ### 1. Capture the transaction Call capture to start collection with Kravia: ```http theme={null} POST /v1/transactions/T12345/capture Authorization: Bearer Content-Type: application/json { "amount": 50000, "items": [ { "line_id": "1", "amount": 50000 } ] } ``` The transaction status stays `AUTHORIZED`; an `INITIATE_CAPTURE` event is appended to record that collection has started. The transaction will move to `CAPTURED` (or `PARTIALLY_CAPTURED`) once Kravia confirms the shopper has paid. For shared capture semantics, see [Transaction management](/docs/checkout/transaction-management#capturing). ### 2. Deliver through your channel Send the invoice to your customer through your own channel, such as email, SMS, a third-party platform, your ERP system, or any other channel. > [!NOTE] > > The PDF may take a moment to become available. Retrieve the transaction again if `kravia:invoice_url` is missing from its metadata. To send the generated invoice, use the `kravia:invoice_url` value from the transaction metadata to retrieve the generated PDF: ```json theme={null} { "metadata": { "kravia:invoice_number": "16788-000018", "kravia:invoice_url": "https://checkout.dintero.com/transaction-attachments/..." } } ``` To generate your own invoice document, use the payment details returned in the `INITIATE_CAPTURE` event metadata: ```json theme={null} { "events": [ { "event": "INITIATE_CAPTURE", "metadata": { "kravia:invoice_number": "16788-000018", "kravia:invoice_id": "98765", "kravia:payment_details:bank_account:bban": "15063092174", "kravia:payment_details:bank_account:iban": "NO0215063092174", "kravia:payment_details:bank_account:swift": "DNBANOKKXXX", "kravia:payment_details:kid": "300000019497814" } } ] } ``` These payment details allow the customer's payment to be matched by Kravia. > [!WARNING] > > Generated invoice documents must match the session data. Kravia uses the session as the source of truth for collection. ## Cancellations Refund is not supported for Kravia. To cancel an invoice (including one delivered through your own channel), use [`POST /v1/transactions/{id}/void`](/docs/checkout/transaction-management#void-cancel). See [Cancellations in Customer checkout](/docs/checkout/kravia/checkout#cancellations) for the full rules per state. ## See also * [Customer Checkout](/docs/checkout/kravia/checkout): customer selects invoice at checkout * [Merchant Initiated](/docs/checkout/kravia/merchant-initiated-payments): create and pay invoices without customer interaction * [Testing](/docs/checkout/testdata/other/checkout-kravia-testdata): test individual and grouped invoice payment scenarios # Kravia merchant initiated payments Source: https://docs.dintero.com/docs/checkout/kravia/merchant-initiated-payments Create and pay Kravia invoices programmatically with one-step or two-step MIT flows for automated invoicing, recurring billing, and back-office workflows. You can create and pay invoices programmatically without the customer going through checkout. There are two approaches depending on your use case: * **One-step**: use the Merchant Initiated Transaction (MIT) endpoint `POST /v1/sessions/pay`. Best for automated invoicing or recurring billing. * **Two-step**: create a session via `POST /v1/sessions` or `POST /v1/sessions-profile`, then call `POST /v1/sessions/{session_id}/pay` to complete it. Useful when you want to set up the session first and pay it later, or when integrating with existing session creation flows. ## Billing address requirements Both flows require a billing address with the same fields as [customer checkout](/docs/checkout/kravia/checkout#billing-address-requirements). The location differs: in one-step it's in `session.order.billing_address`, in two-step it's in the pay request body. ## One-step: Create and pay A single call creates the session and registers the invoice: ```mermaid theme={null} sequenceDiagram participant Merchant participant Dintero Merchant->>Dintero: POST /v1/sessions/pay Dintero-->>Merchant: Transaction AUTHORIZED Note over Dintero: INITIATE_CAPTURE event added
(Kravia begins delivery) ``` Identity verification is automatically skipped. The billing address is provided in `session.order.billing_address` (see [required fields](#billing-address)). The transaction is `AUTHORIZED` on creation and moves to `CAPTURED` once Kravia confirms the shopper has paid. ### B2B example ```http theme={null} POST /v1/sessions/pay Authorization: Bearer Content-Type: application/json { "payment": { "payment_product_type": "kravia.invoice_b2b", "operation": "invoice_payment", "days_until_due": 30 }, "session": { "url": { "callback_url": "https://example.com/callback" }, "order": { "amount": 29900, "currency": "NOK", "vat_amount": 5980, "merchant_reference": "", "items": [ { "description": "Monthly subscription - Premium", "quantity": 1, "amount": 29900, "vat": 25, "line_id": "sub-001" } ], "billing_address": { "first_name": "Ola", "last_name": "Nordmann", "business_name": "Nordmann AS", "organization_number": "123456789", "email": "ola@nordmann.no", "phone_number": "+4799999999", "address_line": "Storgata 1", "postal_code": "0151", "postal_place": "Oslo", "country": "NO" } } } } ``` ### B2C example For B2C invoices, provide `first_name` and `last_name` instead of `business_name` and `organization_number`: ```http theme={null} POST /v1/sessions/pay Authorization: Bearer Content-Type: application/json { "payment": { "payment_product_type": "kravia.invoice_b2c", "operation": "invoice_payment", "days_until_due": 14 }, "session": { "url": { "callback_url": "https://example.com/callback" }, "order": { "amount": 29900, "currency": "NOK", "vat_amount": 5980, "merchant_reference": "", "items": [ { "description": "Online subscription", "quantity": 1, "amount": 29900, "vat": 25, "line_id": "item-1" } ], "billing_address": { "first_name": "Kari", "last_name": "Nordmann", "email": "kari@example.no", "phone_number": "+4798765432", "address_line": "Lillegata 5", "postal_code": "5003", "postal_place": "Bergen", "country": "NO" } } } } ``` ### One-step payment fields | Field | Type | Required | Description | | - | - | - | - | | `payment_product_type` | String | Yes | `"kravia.invoice_b2b"` or `"kravia.invoice_b2c"` | | `operation` | String | Yes | Must be `"invoice_payment"` | | `days_until_due` | Integer | Yes | Days until invoice is due (0-365). Use at least 3 days. | | `invoice_channel` | String | No | `"kravia"` (default) or `"merchant"`. See [Invoice Delivery](/docs/checkout/kravia/invoice-delivery). | ## Two-step: Create session, then pay Create a session first, then programmatically call the pay endpoint. We recommend setting `require_identity_verification: false` on the payment type configuration to skip identity verification. ```mermaid theme={null} sequenceDiagram participant Merchant participant Dintero Merchant->>Dintero: POST /v1/sessions or /v1/sessions-profile Dintero-->>Merchant: Session created (session_id) Merchant->>Dintero: POST /v1/sessions/{session_id}/pay Dintero-->>Merchant: Transaction AUTHORIZED Note over Dintero: INITIATE_CAPTURE event added
(Kravia begins delivery) ``` ### Step 1: Create the session For B2B ```http theme={null} POST /v1/sessions Authorization: Bearer Content-Type: application/json { "url": { "callback_url": "https://example.com/callback" }, "order": { "amount": 29900, "currency": "NOK", "vat_amount": 5980, "merchant_reference": "", "items": [ { "description": "Consulting services", "quantity": 1, "amount": 29900, "vat": 25, "line_id": "item-1" } ] }, "configuration": { "kravia": { "type": "payment_type", "invoice_b2b": { "type": "payment_product_type", "enabled": true, "days_until_due": 30, "require_identity_verification": false, "invoice_channel": "kravia" } } } } ``` For B2C, set the same flags: ```json theme={null} { "configuration": { "kravia": { "type": "payment_type", "invoice_b2c": { "type": "payment_product_type", "enabled": true, "days_until_due": 14, "require_identity_verification": false, "invoice_channel": "kravia" } } } } ``` ### Step 2: Pay the session Call the pay endpoint with the `payment_product_type` and `billing_address`. Note that the billing address is provided in the pay request body, not in the session order: **B2B:** ```http theme={null} POST /v1/sessions/{session_id}/pay Authorization: Bearer Content-Type: application/json { "payment_product_type": "kravia.invoice_b2b", "billing_address": { "first_name": "Ola", "last_name": "Nordmann", "business_name": "Nordmann AS", "organization_number": "123456789", "email": "ola@nordmann.no", "phone_number": "+4799999999", "address_line": "Storgata 1", "postal_code": "0151", "postal_place": "Oslo", "country": "NO" } } ``` **B2C:** ```http theme={null} POST /v1/sessions/{session_id}/pay Authorization: Bearer Content-Type: application/json { "payment_product_type": "kravia.invoice_b2c", "billing_address": { "first_name": "Kari", "last_name": "Nordmann", "email": "kari@example.no", "phone_number": "+4798765432", "address_line": "Lillegata 5", "postal_code": "5003", "postal_place": "Bergen", "country": "NO" } } ``` ### Two-step pay fields | Field | Type | Required | Description | | - | - | - | - | | `payment_product_type` | String | Yes | `"kravia.invoice_b2b"`, `"kravia.invoice_b2b_grouped"`, or `"kravia.invoice_b2c"` | | `billing_address` | Object | Yes | Customer billing details, see [billing address requirements](#billing-address) | ## Response Both approaches return a transaction with status `AUTHORIZED`. An `INITIATE_CAPTURE` event is added automatically as Kravia begins delivery. The transaction moves to `CAPTURED` (or `PARTIALLY_CAPTURED`) once Kravia confirms the shopper has paid. ```json theme={null} { "id": "T12345", "status": "AUTHORIZED", "payment_product_type": "kravia.invoice_b2b", "amount": 29900, "merchant_reference": "inv-2026-001", "metadata": { "kravia:invoice_number": "INV-2026-0001", "kravia:invoice_url": "https://checkout.dintero.com/transaction-attachments/..." }, "events": [ { "event": "AUTHORIZE", "created_at": "2026-01-15T10:30:00Z", "metadata": { "kravia:invoice_date": "2026-01-15", "kravia:invoice_due_date": "2026-02-14", "kravia:invoice_number": "INV-2026-0001" } }, { "event": "INITIATE_CAPTURE", "created_at": "2026-01-15T10:30:00Z", "metadata": { "kravia:invoice_number": "INV-2026-0001", "kravia:invoice_id": "98765", "kravia:payment_details:bank_account:bban": "15063092174", "kravia:payment_details:bank_account:iban": "NO0215063092174", "kravia:payment_details:bank_account:swift": "DNBANOKKXXX", "kravia:payment_details:kid": "300000019497814" } } ] } ``` > [!NOTE] > > The PDF may take a moment to become available. Retrieve the transaction again if `kravia:invoice_url` is missing from its metadata. ## Cancellations Refund is not supported for Kravia. To cancel an invoice, call [`POST /v1/transactions/{id}/void`](/docs/checkout/transaction-management#void-cancel). Void is allowed on `AUTHORIZED` (cancels the invoice) and on `PARTIALLY_CAPTURED` (cancels the remaining amount). See [Cancellations in Customer checkout](/docs/checkout/kravia/checkout#cancellations) for the full rules per state. ## Duplicate prevention Use the `Dintero-Feature-Toggles` header to prevent duplicate invoices: | Toggle | Behavior | | - | - | | `strict-merchant-reference` | Returns `400` if `merchant_reference` already exists in any session | | `strict-success-merchant-reference` | Returns `400` if `merchant_reference` exists in a successfully authorized session. Allows retries after failures. | ```http theme={null} POST /v1/sessions/pay Authorization: Bearer Dintero-Feature-Toggles: strict-success-merchant-reference Content-Type: application/json { ... } ``` ## See also * [Customer Checkout](/docs/checkout/kravia/checkout): customer selects invoice at checkout * [Grouped Invoices](/docs/checkout/kravia/grouped-invoices): consolidate multiple purchases into a single invoice * [Invoice Delivery](/docs/checkout/kravia/invoice-delivery): control who delivers the invoice * [Testing](/docs/checkout/testdata/other/checkout-kravia-testdata): test individual and grouped invoice payment scenarios # Overview Source: https://docs.dintero.com/docs/checkout/kravia/overview Offer Nordic invoice payments in Dintero Checkout via Kravia, including B2B, B2C, and grouped invoices, with distribution, follow-up, and collection. Kravia is an invoicing service that enables businesses to send invoices and manage payments across the Nordics (Norway, Sweden, and Finland). By integrating Kravia into your Dintero checkout, you can offer customers invoice-based payment terms while Kravia handles distribution, follow-up, and collection. ## Payment types | Payment Type | Description | Use Case | | - | - | - | | `kravia.invoice_b2b` | Business-to-business invoicing | One-time invoices to companies | | `kravia.invoice_b2b_grouped` | B2B invoicing with automatic grouping | Multiple purchases consolidated into a single invoice per billing period | | `kravia.invoice_b2c` | Business-to-consumer invoicing | Invoices to individual customers | ## Choosing your integration approach There are two ways to create invoices. For either approach, you can optionally [deliver invoices yourself](/docs/checkout/kravia/invoice-delivery) instead of having them delivered automatically. ```mermaid theme={null} flowchart TD A[Do you have your customer's billing details?] -->|Yes| B[Merchant Initiated] A -->|No| C[Customer Checkout] B --> D{Want to deliver invoices yourself?} C --> D D -->|Yes| E[Enable Custom Distribution] D -->|No| F[Done, delivery is automatic] ``` ## How it works 1. Customer selects invoice payment at checkout, or you create an invoice [via the API](/docs/checkout/kravia/merchant-initiated-payments). 2. Billing information is collected (name, address, email, phone). 3. Identity verification via BankID (if required and enabled for the payment type). 4. Invoice is registered. The transaction is `AUTHORIZED` and an `INITIATE_CAPTURE` event marks the start of collection, either automatically when Kravia delivers the invoice, or when you call `POST /v1/transactions/{id}/capture` before delivering it yourself with [merchant delivery](/docs/checkout/kravia/invoice-delivery). 5. Customer pays the invoice via their bank. Kravia notifies Dintero, and the transaction moves to `CAPTURED` (or `PARTIALLY_CAPTURED` for partial payment). 6. Dintero settles the funds to the merchant, tracked separately on `settlement_status`. ### Transaction lifecycle Kravia transactions reuse the standard Dintero transaction states. See [Transaction management](/docs/checkout/transaction-management) for the shared capture/void model. ```mermaid theme={null} stateDiagram direction TB state idv <> [*] --> idv: Customer checkout [*] --> AUTHORIZED: Merchant initiated idv --> AUTHORIZED: No identity verification idv --> ON_HOLD: Identity verification enabled ON_HOLD --> AUTHORIZED: Verified ON_HOLD --> FAILED: Verification failed AUTHORIZED --> CAPTURED: Shopper paid in full AUTHORIZED --> PARTIALLY_CAPTURED: Shopper paid in part AUTHORIZED --> AUTHORIZATION_VOIDED: Void PARTIALLY_CAPTURED --> CAPTURED: Remaining paid PARTIALLY_CAPTURED --> AUTHORIZATION_VOIDED: Void remaining ``` Key points: * `AUTHORIZED`: Invoice exists with Kravia. An `INITIATE_CAPTURE` event is added when collection starts (automatically for Kravia delivery, manually via `POST /capture` for [merchant delivery](/docs/checkout/kravia/invoice-delivery)). The status does not change at this point. * `CAPTURED` / `PARTIALLY_CAPTURED`: Shopper has paid the invoice in full or in part. Triggered by Kravia's payment notification. * `AUTHORIZATION_VOIDED`: Invoice cancelled with Kravia via `POST /v1/transactions/{id}/void`. Allowed from `AUTHORIZED` or `PARTIALLY_CAPTURED` (cancels the remaining amount). * Refund is not supported for Kravia, only void. Funds in transit during a void, and any overpayment, are automatically refunded to the shopper by Kravia. * Settlement to the merchant is tracked on `settlement_status` (`NOT_SETTLED`, `PARTIALLY_SETTLED`, `SETTLED`) and is independent of the transaction status. ### Liability Unlike card-based payments, invoice payments do not reserve or guarantee funds at the time of authorization. A `CAPTURED` status means Kravia has confirmed that the customer paid the invoice, but funds are not guaranteed to have arrived in the merchant's account. That is only confirmed when `settlement_status` is `SETTLED`. If a customer does not pay the invoice, the merchant's receipt of funds depends on Kravia's collection process and the specific contract terms. ## Next steps * **[Customer Checkout](/docs/checkout/kravia/checkout)**: customer selects invoice at checkout, includes configuration options, identity verification, invoice dates, and billing address details * **[Grouped Invoices](/docs/checkout/kravia/grouped-invoices)**: consolidate multiple purchases into a single invoice per billing period * **[Merchant Initiated](/docs/checkout/kravia/merchant-initiated-payments)**: create and pay invoices without customer interaction * **[Invoice Delivery](/docs/checkout/kravia/invoice-delivery)**: control who delivers the invoice, automatic or you * **[Testing](/docs/checkout/testdata/other/checkout-kravia-testdata)**: test individual and grouped invoice payment scenarios # PCI DSS compliance for merchants Source: https://docs.dintero.com/docs/checkout/merchant-pci-dss-compliance Understand merchant PCI DSS responsibilities when using Dintero, a Level 1 Service Provider, and learn best practices for protecting cardholder data. PCI DSS (Payment Card Industry Data Security Standard) is a set of security standards designed to ensure that all companies that process, store or transmit credit card information maintain a secure environment. As a merchant, you are part of the payment processing ecosystem and need to comply with PCI DSS requirements to protect your customers' credit card information. This guide provides merchants who are customers of Dintero with a comprehensive overview of PCI DSS compliance requirements and best practices, but it is important to note that this guide is not a substitute for professional advice from a qualified security expert. ## Dintero's responsibilities Dintero is certified as a Level 1 Service Provider by the PCI Security Standards Council. This means that Dintero has undergone rigorous security assessments and has demonstrated its ability to meet the highest PCI DSS compliance requirements. When you are using Dintero's payment processing services, all card data is encrypted and securely transmitted to our servers, so that you as a merchant cannot access or store it yourself. Accepting credit card payments on your website, app, or in your physical store means you retain some PCI scope, even with a Dintero integration. ## Your role as a Dintero merchant While Dintero is a certified PCI DSS Level 1 Service Provider, you still have some responsibilities to ensure your own environment is secure. Your compliance is typically simplified to completing a **Self-Assessment Questionnaire (SAQ)**. Given that Dintero handles all sensitive card data, you will likely be eligible for **SAQ A**. This is the easiest and most common SAQ, as it applies to merchants who outsource all cardholder data processing to a PCI DSS-validated third party and do not store, process, or transmit any cardholder data on their own systems or premises. *** ## Your simplified compliance steps 1. **Understand Your Environment**: Because Dintero handles the sensitive data, your "Cardholder Data Environment" (CDE) is limited. You must ensure that any system or network that interacts with your Dintero integration is secure. 2. **Complete the SAQ A**: You are required to complete and submit an annual [SAQ A](https://docs-prv.pcisecuritystandards.org/SAQ%20\(Assessment\)/SAQ/PCI-DSS-v4-0-1-SAQ-A.pdf) to [merchant-pci@dintero.com](mailto:merchant-pci@dintero.com). This questionnaire attests that you do not store, process, or transmit cardholder data and that you are using a validated third-party service provider (Dintero) for payment processing. 3. **Secure Your Systems**: Even though you don't handle card data directly, you must still maintain a secure environment. This includes: * Using strong passwords and unique user IDs for all systems. * Not using vendor-supplied defaults for system passwords and other security parameters. * Using and regularly updating antivirus software. * Protecting all systems from malware. * Having a formal security policy in place. 4. **Monitor Your Website**: You must confirm that your site is not susceptible to attacks from scripts that could affect the merchant's e-commerce system(s). By following these steps, you can confidently demonstrate your PCI DSS compliance while leveraging Dintero's secure payment services. # Pay in store Source: https://docs.dintero.com/docs/checkout/pay-in-store Allow customers to reserve an order online and pay in store. > [card] [Looking for in-person payments?](/docs/checkout/in-person/overview) > > In-person payments let customers pay directly on a Dintero terminal. ## Overview Merchants can offer customers the flexibility to reserve items online and pay in-person at pickup, accepting any payment method available at the physical location. > [!NOTE] > > Pay in store is **only supported for Dintero Checkout Express sessions**. > > It works by setting the payment amount to zero when the customer selects a pay-in-store shipping option. ## Pay in store flow (for payer) When the payer opens the checkout they get the option to select **"Pay in-store"** after they have entered their customer details, as shown below: **1. Select Pay in-store** ![Pay in store input](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/pay-in-store-input.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=8672ec2b53f76e9d8b9452052f6c303d) **2. Select which store to pay at** ![Pay in store selected](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/pay-in-store-select.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=b43a21b3575814b58c5b4e9c71b6efbf) **3. It is possible to add multiple stores to pay at** ![Pay in store multiple](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/pay-in-store-multiple.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=026eaed76babba3b01fdb2dfcea81586) **4. Pay in-store** ![Pay in store payment](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/pay-in-store-payment.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=1d30a06d5fabcbb29e14b1804f4d7855) The only payment method available for pay in store is `dintero.zero`. It will be presented as the only payment option in the checkout ## Pay now and pick up in-store To offer "pay now and pick up in-store," you must configure 2 shipping options in the session: 1. One shipping option with **"pay in-store"** defined 2. One shipping option without **"pay in-store"** Both shipping options must have the same `operator` value. ### Example request The highlighted lines in the example are needed to enable "pay now and pick up in-store": * [`configuration.dintero.zero`](/api-reference/session/checkout_session_profile_post#body-configuration-dintero-zero) enables the payment type, and * [`pay_in_store`](/api-reference/session/checkout_session_profile_post#body-express-shipping-options-items-pay-in-store) marks a shipping option as pay in store. * Both shipping options must have the same `operator` value. ```http {25-35, 44, 62, 73-75} theme={null} POST https://api.dintero.com/v1/accounts/{account_id}/payments/sessions-profile Authorization: Bearer Content-Type: application/json { "url": { "return_url": "https://example.com/accept", "callback_url": "https://example.com/callback?method=GET", "merchant_terms_url": "https://example.com/terms.html" }, "order": { "amount": 10000, "currency": "NOK", "items": [ { "id": "123", "name": "Product 1", "quantity": 1, "unit_price": 10000 } ], "merchant_reference": "string" }, "profile_id": "", "configuration": { "active_payment_types": { "enabled": true }, "dintero": { "type": "payment_type", "zero": { "type": "payment_product_type", "enabled": true, "payability": "payable" } } }, "express": { "shipping_options": [ { "id": "StoreName.1234", "vat": 0, "title": "Pay now and pick up in store", "amount": 0, "line_id": "StoreName.1234_1_pickup", "operator": "StoreName", "vat_amount": 0, "delivery_method": "pick_up", "pick_up_address": { "country": "NO", "first_name": "StoreName", "postal_code": "0000", "address_line": "Address 1", "postal_place": "OSLO", "phone_number": "12345678" } }, { "id": "StoreName.1234", "vat": 0, "title": "Order and pay in store", "amount": 0, "line_id": "StoreName.1234_1", "operator": "StoreName", "vat_amount": 0, "delivery_method": "pick_up", "pick_up_address": { "country": "NO", "first_name": "StoreName", "postal_code": "0000", "address_line": "Address 1", "postal_place": "OSLO", "phone_number": "12345678" }, "pay_in_store": { "type": "full" } } ] } } ``` # Hosted payment sessions Source: https://docs.dintero.com/docs/checkout/payment-hosted Skip the Dintero Checkout and complete payment via the Vipps or MobilePay hosted payment page If a session contains only Vipps or MobilePay, you can skip opening the Dintero Checkout and instead open the payment method's hosted payment page directly. > [!NOTE] > > Testing hosted payments in the sandbox environment is only possible with the direct `vipps` integration or `dintero_psp.vipps`, so some testing will have to be done with real payments. ## Creating a hosted payment session Set `configuration.channel=hosted` for sessions that contain a single payment method. **Request** ```json highlight={11-18} theme={null} { "url": { "return_url": "http://merchant.com/handle_payment/ORDER123/return", "callback_url": "http://merchant.com/handle_payment/ORDER123/callback" }, "order": { "amount": "500", "currency": "NOK", "merchant_reference": "ORDER123" }, "configuration": { "channel": "hosted", "dintero_psp": { "vipps": { "enabled": true } } } } ``` **Response** ```json theme={null} { "id": "P12345678.55Q4CC1WuVJdgCssZfrf5a", "url": "https://pay.vipps.no/dwo-api-application/v1/deeplink/vippsgateway?v=2&token={vipps_token}" } ``` Open the `url` in the end users devices to complete the payment. > [!WARNING] > > Do not embed the hosted `url` when opening it, so that the hosted page can act as a universal link and launch the Vipps or MobilePay app. Hosted payments are not compatible with embedding via the frontend `Dintero.Checkout.Web.SDK`. ### Payment finished or cancelled After the user finishes or cancels the payment, they are returned to the `return_url`. Dintero appends the following query parameters: | Name | Description | Always present | | - | - | - | | transaction_id | The transaction ID for the payment | No | | session_id | The session ID | No | | error | Error code identifying the cause | No | | merchant_reference | The merchant reference | Yes | ## Fallback to the Dintero Checkout If a session specifies `configuration.channel=hosted` but its payment method does not support hosted payments, or the session contains more than one payment method, the `url` returned on session creation opens the Dintero Checkout instead, where the user can complete their payment. The url will also fall back to Dintero Checkout for [Checkout Express](/docs/checkout/express#what-is-checkout-express) sessions, so the end user can submit their shipping and billing information and select a shipping option before payment. ## Handling dangling browser tabs on mobile On mobile devices, the hosted payment acts as a universal link and tries to open the payment directly in the payment method's native app (e.g. Vipps or MobilePay). If the app is not installed, the browser navigates to the hosted payment page instead. When a payment app is opened via a universal link, the page the user was visiting remains open in the browser. After the payment completes, the `return_url` opens in a *new* browser tab, leaving the original page open as a dangling pending-payment page. To handle this, we recommend one or both of the following: * **Update the UI before redirecting.** Before opening the hosted payment link, change the payment page to show messaging that the user is being redirected to complete payment. * **Re-check status on focus.** Add code that runs when the tab regains focus to check the session status. If the user returns to the dangling page, you can then update it to show that the payment completed, or prompt them to try again. # In-app payments with deep links Source: https://docs.dintero.com/docs/checkout/payment-in-app Open your merchant app from Dintero Checkout using deep links after a Vipps or wallet payment, and how to test in-app flows in the sandbox environment. Merchant may implement deep-linking to open the merchant app after the user has finished (opr cancelled) the payment. > [!NOTE] > > Testing in-app payments in the sandbox environment is only possible with the direct Vipps integration, > so some of the testing will have to be done with real payments. > > For these cases, ask Dintero for the direct Vipps integration to be enabled on your sandbox account. ## In app Merchant may use the `configuration.channel=in_app` for payment done from mobile devices, where the `url.return_url` can be set to the application's appswitch URL **Request** ```json theme={null} { "url": { "return_url": "merchantApp://result?myAppData", "callback_url": "https://example.com/callback?method=GET" }, "order": { "amount": "500", "currency": "NOK", "merchant_reference": "ORDER123" }, "configuration": { "channel": "in_app", "bambora": { "vipps": { "enabled": true } } } } ``` **Response** ```json theme={null} { "id": "P12345678.55Q4CC1WuVJdgCssZfrf5a", "url": "vipps://?token=XXXX" } ``` > [!NOTE] > > The URL included when the session is created will be app specific, e.g. Vipps > if the session is limited to a single payment option, otherwise it will be a link > to Dintero Checkout where user is presented all payment options ### Payment finished or cancelled After the user has finished (or cancelled) the payment, the user is returned to the specific app `return_url`, Dintero will append query parameters to the `return_url` | Name | Description | Required | | - | - | - | | transaction_id | The transaction for the payment | false | | session_id | The session payment id | false | | error | Error code identify cause | false | | merchant_reference | Merchant reference | true | **Example URL** ```text theme={null} merchantApp://result?myAppData&transaction_id=T12345678.abc&merchant_reference=mref123&session_id=T12345678.abd ``` ## App-switching (deep-linking) The merchant can enable app switching by including `initial_recipient=merchant` in `return_url`, the payment app will then switch directly to the merchant app after the user has finished (or cancelled) the payment. You will in this case be required to do some more work to make sure that the session/transaction has the correct status. The next steps depends on the payment method that is used. * For Dintero PSP Vipps you will receive `payment_return_url` as a query parameter in the URL. * For Swish you will receive `payment_return_url` as a query parameter in the URL, that can initially return 202 Accepted while waiting on confirmation from Swish * For Bambora Vipps you will receive `epayreturn` as a query parameter in the URL. * For a direct Vipps integration you will receive a transaction_id query parameter in the URL. ### If return url contains payment_return_url If the return url contains `payment_return_url`, you will have to do a GET request to this URL. The response will contain a Location header that contains a transaction_id or session_id. You can then use the `transaction_id` or `session_id` to get the status of the payment. Full process: ```mermaid theme={null} sequenceDiagram title Swish App-switching after payment participant APP as Your app participant Swish participant DC as Dintero Checkout Swish->>APP: merchantApp://result?payment_return_url=redirect_url_a APP->>DC: GET redirect_url_a alt Accepted DC-->>APP: 202 Retry-After: 2 else Completed DC-->>APP: 302 Location: redirect_url_b?merchant_reference_foo&session_id=bar&transaction_id=baz end APP->>DC: GET /sessions/bar OR /transactions/baz ``` > [!NOTE] > > The `payment_return_url` may initially return `202 Accepted` if the payment > confirmation is not yet ready. > > A `Retry-After` header indicates when to check again. > Once ready, a `302 Found` redirect is returned to the external callback URL. ### If return url contains epayreturn If the return url contains `epayreturn`, you will have to do a GET request to this URL. If the response does not contain epayreturn, you should instead jump to "Polling the session or transaction". The response will contain a Location header that you also need to perform a GET request to. After this, you should get another response with a location header, that contains a transaction_id or session_id. After this back and forth, you should have a transaction_id or session_id that you can use to get the status of the payment. Full process: ```mermaid theme={null} sequenceDiagram title Bambora Vipps App-switching after payment participant APP as Your app participant VIPPS as Vipps participant Bambora participant DC as Dintero Checkout VIPPS->>APP: merchantApp://result?epayreturn=redirect_url_a APP->>Bambora: GET redirect_url_a Bambora-->>APP: 302 Location: redirect_url_b APP->>DC: GET redirect_url_b DC-->>APP: 302 Location: redirect_url_b?merchant_reference_foo&session_id=bar&transaction_id=baz APP->>DC: GET /sessions/bar OR /transactions/baz ``` ### Polling the session or transaction You will now be required to poll for status on the payment by using the `session_id` or `transaction_id` provided as the status on the payment may not be ready when the merchant app receive the switch from the payment app. * [GET /v1/sessions/\{session_id}][get session details] * [GET /v1/transactions/\{transaction_id}][get transaction details] Poll the transaction until it has been updated with one of these statuses: * AUTHORIZED * CAPTURED * FAILED > [!NOTE] > > In case no `transaction_id` is included in the return_url, poll the session to > get the `transaction_id` > > The `initial_recipient=merchant` option is not supported for: > > * payex.vipps > * payex.swish > * bambora.mobilepay ```json theme={null} { "url": { "return_url": "merchantApp://result?myAppData&initial_recipient=merchant", "callback_url": "https://example.com/callback?method=GET" }, "order": { "amount": "500", "currency": "NOK", "merchant_reference": "ORDER123" }, "configuration": { "channel": "in_app", "bambora": { "vipps": { "enabled": true } } } } ``` ## Minimal UI mode when embedding the Checkout To embed a minimal version of Dintero Checkout, ideal for showing a single payment option in web UI (like a card payment form), append a `ui` query parameter set to `inline` to the session link. **Example:** ```text theme={null} https://checkout.api.dintero.com/v1/view/{session_id}/?ui=inline ``` [get session details]: /api-reference/session/checkout_session_get [get transaction details]: /api-reference/transactions/transactions_id_get # Payment link by SMS or push Source: https://docs.dintero.com/docs/checkout/payment-link-by-sms Send a Dintero Checkout payment link by SMS or push notification using payment profile settings, payment-link configuration, or the Checkout API. In some cases you might want to send an SMS to the customer with a link to the checkout when the session is created. There are several ways to send SMS-messages when creating a session: * Enable SMS in Payment link in Backoffice * Enable SMS in payment profile via Backoffice * Enable via the API > [!NOTE] > > SMS messages are not sent for test sessions. ## Enable SMS in Payment link in Backoffice To send an SMS when using the Payment link in Backoffice, choose **Send by** → **SMS/Push** and specify the phone number. ![Enable SMS/Push in Payment link in Backoffice](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/backoffice/enable_sms_push_payment_link.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=085d019b3407dbe333d7ac7dc6576e1e) ## Enable SMS in payment profile via Backoffice If you're using payment profiles, SMS is quite easy to turn on. Simply open Backoffice and go to **Settings** → **Payment profiles**. Choose your payment profile from the list (or create a new one), click edit and tick the box that says **"Send payment link via SMS to customers"**. Save the payment profile. ![Enable SMS/Push in payment profile via Backoffice](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/backoffice/enable_sms_push_profile.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=5bbd1d90f18cbab29cc0a4bef9030dfe) Now, when creating a session with this payment profile, your customer will receive an SMS. ## Enable SMS via the API When using the API, you can enable SMS either through payment profiles or directly when creating the session. * [Creating payment profile](/checkout-api/profiles/admin_session_profile_post) * [Editing payment profile](/checkout-api/profiles/admin_session_profile_details_put) * [Creating a session](/checkout-api/session/checkout_session_post) > [!NOTE] > > To create payments with a payment profile, > use [Create checkout session from profile](/api-reference/session/checkout_session_profile_post) > . For each of these cases, extend the request body with the following fields: ```json theme={null} { "configuration": { "publish": [ { "type": "checkout-link", "channel": "sms" } ] } } ``` ## Direct push messages instead of SMS For the following payment types, we support direct push messages: * Vipps * Swish * MobilePay To send push payments instead of SMS-messages for one of these payment types, these conditions must be met: * The session should only contain that single payment type * Publish is configured as the example above. # Payment profiles Source: https://docs.dintero.com/docs/checkout/payment-profiles Manage payment methods centrally with Dintero payment profiles in Backoffice so you can add or change methods without redeploying integration code. A payment profile is a named payment configuration stored on your Dintero account. Instead of listing every payment method in each session request, you reference the profile by its `profile_id`, and the checkout uses the payment methods configured on the profile. The main benefit is that the payment configuration lives in [Dintero Backoffice], not in your code. You can enable a new payment method, change the order methods are displayed in, or adjust the checkout theme without changing or redeploying your integration. ## Creating a payment profile Every new account has a `default` payment profile. To create additional profiles, go to [Dintero Backoffice] → **Settings** → **Payment profiles**. Multiple profiles are useful when different parts of your business need different payment setups, for example one profile for your web shop and another for in-store payments, or separate profiles for different markets. ## Creating a session with a payment profile Create the session with a POST request to `https://api.dintero.com/v1/accounts/{account_id}/payments/sessions-profile`, referencing the profile in `profile_id`. See the [create session from profile] endpoint for all available fields. ```json lines highlight={22} theme={null} { "url": { "return_url": "https://example.com/return", "callback_url": "https://example.com/callback" }, "order": { "amount": 29990, "currency": "NOK", "merchant_reference": "merchants_order_number", "items": [ { "id": "chair-1", "line_id": "1", "description": "Stablestol", "quantity": 1, "amount": 29990, "vat_amount": 6000, "vat": 25 } ] }, "profile_id": "default" } ``` The response contains the session ID and the URL where the customer completes the payment: ```json theme={null} { "id": "{session_id}", "url": "https://checkout.api.dintero.com/v1/view/{session_id}/" } ``` ## Sessions without a payment profile It is also possible to create sessions where the full payment configuration is included in the request, using the [create session] endpoint. We recommend using payment profiles instead, since they let you add new payment methods without changing any code. [Dintero Backoffice]: https://backoffice.dintero.com [create session from profile]: /api-reference/session/checkout_session_profile_post [create session]: /checkout-api/session/checkout_session_post # Dintero settlement report formats Source: https://docs.dintero.com/docs/checkout/payout-reports-dintero-reports Receive Dintero settlement reports for all payment providers in PDF, XML, CSV, and JSON formats, delivered by email or available in Backoffice. Dintero produces settlement reports in a common format for all payment providers, send it to your email and put it up in the Backoffice. We provide PDF-, XML-, CSV-, and JSON-versions of the reports. **Examples:** | Filetype | Example | | - | - | | PDF | [PDF](/assets/payout-report-examples/example_settlement.pdf) | | XML | [XML](/assets/payout-report-examples/example_settlement.xml) - [XSD](/assets/payout-report-examples/dintero-settlement-1.0.xsd) | | CSV | [CSV](/assets/payout-report-examples/example_settlement.csv) | | JSON | [JSON](/assets/payout-report-examples/example_settlement.json) | ## CSV columns The CSV report has one row per settled transaction event. Settlement-level values, such as `AccountId` and `SettlementDate`, repeat on every row. * Fields are separated by `;`. * Text values are quoted with `"`. Numbers are not quoted. * The file is UTF-8 with a byte order mark (BOM). * Dates use the `YYYY-MM-DD` format. * Amounts are in the main currency unit (for example, `50` for 50 NOK), with `,` as the decimal separator. The currency is not included in the CSV. * A settlement with no transactions produces an empty file with no header row. > [!WARNING] > > **`TransactionType` holds the payment product type in CSV, not the record type.** In CSV, `TransactionType` holds the [payment product type](/docs/glossary), for example `bambora.creditcard`. In XML, `` holds the record type, for example `settlement`, and the payment product type is in ``. If you move an integration between CSV and XML, map these columns explicitly. > > **`Amount` is the gross amount in CSV.** In CSV, `Amount` is the amount before fees and `NetAmount` is the amount after fees. In XML, `` is the amount after fees, and so is `amount` in JSON. ### Always-present columns For CSV reports with at least one transaction, these columns appear in this order. | Column | Description | | - | - | | `AccountId` | The Dintero account ID, for example `P12345678`. | | `MerchantName` | The business name from the account's billing settings. | | `SettlementReference` | The provider's reference for the settlement. | | `SettlementDate` | The date the settlement was paid out. | | `AmountCaptured` | The captured amount. | | `AmountRefunded` | The refunded amount, as a negative number. | | `ChargebackAmount` | The chargeback amount. Empty when there is no chargeback. | | `Amount` | The gross amount, before fees. | | `Fee` | The fee. `-` when there is no fee. | | `NetAmount` | The net amount, after fees. | | `VatAmount` | The VAT amount. Empty when there is no VAT. | | `TransactionDate` | The date of the transaction event. | | `TransactionID` | The Dintero transaction ID. Empty when not available. | | `SessionId` | The Dintero session ID. Empty when not available. | | `TransactionType` | The [payment product type](/docs/glossary), for example `bambora.creditcard`. See the warning above. | | `Reference` | The `merchant_reference` of the transaction. | | `Reference2` | The `merchant_reference_2` of the transaction. Empty when not set. | | `EventReference` | The `event_reference` of the transaction event, or the `capture_reference` or `refund_reference` when set. Empty when not set. | | `CardBrand` | The card brand, for example `Visa`. Empty when not available. | | `CardRegion` | The card region, for example `eea`. Empty when not available. | | `CardType` | The card type. Empty when not available. | | `Channel` | The payment channel, for example `ecommerce`. Empty when not available. | ### Conditional columns These columns appear only when at least one transaction in the settlement has a value for them. When a column appears, rows without a value have an empty cell. When they appear, they come after the always-present columns, in this order. | Column | Appears when | Description | | - | - | - | | `StoreId` | Any transaction in the settlement has a store ID. | The store ID of the transaction. | | `PayoutDestinationId` | Any transaction in the settlement has a payout destination. | The [payout destination](/docs/checkout/split-payment/add-payout-destinations) of the transaction. | | `TerminalId` | Any transaction in the settlement has a terminal ID. | The ID of the payment terminal used for an [in-person payment](/docs/checkout/in-person/overview). | | `StorePayoutDestinationId` | Any transaction in the settlement has a store payout destination. | The payout destination of the store. | | `EventCorrelationId` | Any transaction in the settlement has an event correlation ID. | The ID for matching the row to a transaction event. | > [!TIP] > > Read columns by header name, not by position. Conditional columns change the position of the columns that follow them, and they can differ between two reports for the same account. ## Identify transaction rows Each row in a report is one settled transaction event, not one transaction. In CSV this is a row, in XML a `` element, and in JSON an entry in `transactions`. A single Dintero transaction can have several settled events. For example, two partial captures and a refund on the same payment produce three rows. All three rows have the same transaction ID (`TransactionID` in CSV and XML, `transaction_id` in JSON). The transaction ID is therefore not a unique key for a row. The event correlation ID is optional: XML omits the element and JSON omits the property when an event has none; CSV includes the `EventCorrelationId` column when any row has a value and leaves cells empty otherwise. The [JSON example](/assets/payout-report-examples/example_settlement.json) shows several rows with the same `transaction_id` and different `event_correlation_id` values. ## Webhooks We provide the webhook `settlement_add` when a report has been created. See [Webhooks](/docs/checkout/webhooks) to set it up. ## API The settlement API is documented [here](/api-reference/settlements/aid_settlements_list). # Settlement reports introduction Source: https://docs.dintero.com/docs/checkout/payout-reports-introduction Find Dintero payout settlement reports in Backoffice and learn how to generate test reports to verify your accounting and reconciliation workflows. Each payout to your bank account leads to a settlement report. The reports are visible in Backoffice, under **Reports** → **Payout reports**. These reports are generated automatically and contain detailed information about the transactions that were settled during the payout period. See [Dintero Reports] for a description of the format. #### Generate a test settlement report You can use the [Generate a test settlement report] API to generate test settlements for your test transactions [setting up Vipps]: /docs/checkout/checkout-vipps-settlements [Dintero Reports]: /docs/checkout/payout-reports-dintero-reports [Generate a test settlement report]: /api-reference/settlements/aid_settlement_generate_test_report # Postman guide for Dintero Checkout Source: https://docs.dintero.com/docs/checkout/postman-checkout-guide Test the Dintero Checkout API in Postman: set up your API client, get an access token, create sessions, and run common requests end to end. ## Prerequisites * Merchant account [signup] * Create [Checkout API client] via [Dintero Backoffice] * Session profile. Log in to [Dintero Backoffice] → Settings → Payment Profiles * Download or log in to [Postman] ## First steps Download these files: * [Postman Collection](/mintlify-docs/postman/checkout.postman.v1.0.json) * [Sandbox Environment](/mintlify-docs/postman/checkout.postman.environment.sandbox.v1.0.json) When Postman is opened, import the Postman Collection using the `Import`-button in the upper left corner. Now, go to **Manage Environments**, and import the Sandbox Environment. Now, edit the Sandbox Environment with the properties that are unique to you: * **Client_Id** (e.g. **13246c33-6b84-423c-9a12-21db98a29424**) * **Client_Secret** (e.g. **b8ab258b-461e-4cf3-b425-ba6631027d9d**) * **Account_Id** (e.g. **T41112484**) Make sure you use credentials from the sandbox/test-environment, and an accountId prefixed with a `T`. You can also set a payment profile id, see prerequisites. * sessionProfileId This should also be prefixed with a `T`. ## Fetching a token Now, you should be able to fetch a token. Go to the `Get Token`-request and push the **Send-button**. If everything goes well, you'll get an access_token that you can use for calls to the Checkout API. ## Create a session Go to **Create a checkout session**. You can edit the body if you want to, and then push **Send**. A session will be created, and you will get a URL that you can use to pay it. You can also create a session using the **Create checkout session from profile** if you've configured the `sessionProfileId` variable. You can cancel the session using the `Cancel session`-request before paying. ## After paying When the session is paid, use the **Get checkout session details**-request to see the status of the session. If the payment succeeded, there should be a `transaction_id`-property on the session. This will be saved as an environment variable in Postman. You can now fetch the transaction using the **Get a transaction**-request. You can also void it, capture it and make a refund after capturing. ## Further To customize your requests, check out the [checkout api] for all the possibilities. [signup]: https://onboarding.dintero.com [Dintero Backoffice]: https://backoffice.dintero.com [checkout api]: /checkout-api/session/checkout_session_profile_post [Checkout API client]: /docs/checkout/checkout-client [Postman]: https://www.postman.com/ # Quickstart Source: https://docs.dintero.com/docs/checkout/quickstart Go from zero to your first Dintero Checkout payment in minutes. Create credentials, authenticate, build a checkout session, and handle the payment result. This guide walks you through the complete flow: create credentials, authenticate, create a checkout session, and handle the payment result. ## How it works Every Dintero integration follows the same pattern: **1. Get credentials** Create an API client in [Backoffice](https://backoffice.dintero.com/) and save your Client ID and Client Secret. **2. Authenticate** Exchange credentials for a bearer token. **3. Create a session** Send your order details to Dintero and get back a checkout URL. **4. Handle the result** Dintero calls your server with the transaction result. Capture, refund, or void as needed. ## Prerequisites * A Dintero account ([sign up here](https://onboarding.dintero.com/)) * Access to [Dintero Backoffice](https://backoffice.dintero.com/) * A server that can make HTTP requests ## Sandbox vs production Every Dintero account has two environments, identified by the account ID prefix: | Prefix | Environment | Example | Purpose | | - | - | - | - | | `T` | Sandbox | `T12345678` | No real money, use [test cards](/docs/checkout/checkout-testdata) | | `P` | Production | `P12345678` | Live, real payments | > [!NOTE] > > Start with your sandbox account (`T` prefix). Switch to production by creating new API credentials on your `P` account when you're ready to go live. ### Get a sandbox account If your company is registered (for example, a Norwegian AS), create your Dintero account yourself through [onboarding](https://onboarding.dintero.com/). Signing up gives you a sandbox account right away, so you can start testing without contacting Dintero. You don't need to complete KYC (Know Your Customer) verification to use the sandbox account. KYC is only required when you're ready to accept real payments on your production account. ## Step 1: Create API credentials **1. Open Backoffice** Go to **Settings** > **API clients** (under API & Integrations). **2. Create a client** Click **Create new API client** > **Checkout client**, enter your website URL, and click **Create**. **3. Save credentials** Copy the **Client ID** and **Client Secret** immediately. > [!WARNING] > > The Client Secret is shown only once. Store it securely. You cannot retrieve it later. For a visual walkthrough, see the [API client](/docs/checkout/checkout-client) page. ## Step 2: Get an access token Exchange your credentials for a bearer token using the OAuth 2.0 client credentials flow. ```bash cURL theme={null} curl -X POST https://api.dintero.com/v1/accounts/T12345678/auth/token \ -u "CLIENT_ID:CLIENT_SECRET" \ -H "Content-Type: application/json" \ -d '{ "grant_type": "client_credentials", "audience": "https://api.dintero.com/v1/accounts/T12345678" }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.dintero.com/v1/accounts/T12345678/auth/token", auth=("CLIENT_ID", "CLIENT_SECRET"), headers={"Content-Type": "application/json"}, json={ "grant_type": "client_credentials", "audience": "https://api.dintero.com/v1/accounts/T12345678", }, ) access_token = response.json()["access_token"] ``` ```javascript Node.js theme={null} const response = await fetch( "https://api.dintero.com/v1/accounts/T12345678/auth/token", { method: "POST", headers: { "Content-Type": "application/json", Authorization: "Basic " + Buffer.from("CLIENT_ID:CLIENT_SECRET").toString("base64"), }, body: JSON.stringify({ grant_type: "client_credentials", audience: "https://api.dintero.com/v1/accounts/T12345678", }), } ); const { access_token } = await response.json(); ``` The response includes a token valid for 4 hours: ```json theme={null} { "access_token": "eyJhbGci...t7P4", "token_type": "Bearer", "expires_in": 14400 } ``` Use this token in the `Authorization: Bearer {access_token}` header for all API calls. ## Step 3: Create a checkout session A session represents a customer's order. Send the order details and get back a checkout URL. > [!NOTE] > > The Checkout API is now available under `https://api.dintero.com/v1/accounts/{account_id}/payments/`. > > The previous `https://checkout.dintero.com/v1/` base is still supported, so existing integrations continue to work without changes. ```bash cURL theme={null} curl -X POST https://api.dintero.com/v1/accounts/{account_id}/payments/sessions-profile \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "url": { "return_url": "https://example.com/thankyou", "callback_url": "https://example.com/callback" }, "order": { "amount": 29990, "currency": "NOK", "merchant_reference": "order-001", "items": [ { "id": "item-1", "line_id": "1", "description": "Blue T-Shirt", "quantity": 1, "amount": 29990, "vat_amount": 5998, "vat": 25 } ] }, "profile_id": "default" }' ``` ```python Python theme={null} response = requests.post( "https://api.dintero.com/v1/accounts/{account_id}/payments/sessions-profile", headers={"Authorization": "Bearer ACCESS_TOKEN"}, json={ "url": { "return_url": "https://example.com/thankyou", "callback_url": "https://example.com/callback", }, "order": { "amount": 29990, # 299.90 NOK "currency": "NOK", "merchant_reference": "order-001", "items": [ { "id": "item-1", "line_id": "1", "description": "Blue T-Shirt", "quantity": 1, "amount": 29990, "vat_amount": 5998, "vat": 25, } ], }, "profile_id": "default", }, ) session = response.json() ``` ```javascript Node.js theme={null} const response = await fetch( "https://api.dintero.com/v1/accounts/{account_id}/payments/sessions-profile", { method: "POST", headers: { Authorization: "Bearer ACCESS_TOKEN", "Content-Type": "application/json", }, body: JSON.stringify({ url: { return_url: "https://example.com/thankyou", callback_url: "https://example.com/callback", }, order: { amount: 29990, // 299.90 NOK currency: "NOK", merchant_reference: "order-001", items: [ { id: "item-1", line_id: "1", description: "Blue T-Shirt", quantity: 1, amount: 29990, vat_amount: 5998, vat: 25, }, ], }, profile_id: "default", }), } ); const session = await response.json(); ``` > [!NOTE] > > Amounts are in the smallest currency unit. `299.90 NOK` = `29990`. The response returns a session ID and checkout URL: ```json theme={null} { "id": "T12345678.xxxxxxxxxxxxxxxxxxxx", "url": "https://checkout.dintero.com/v1/view/T12345678.xxxxxxxxxxxxxxxxxxxx" } ``` ## Step 4: Display the checkout Show the checkout to your customer using the [Web SDK](https://github.com/Dintero/Dintero.Checkout.Web.SDK). Install it with npm: ```sh theme={null} npm install @dintero/checkout-web-sdk ``` > [!NOTE] > > Not sure which approach to use? > > **Redirect** sends the customer to a Dintero-hosted page, with minimal setup, no iframe. **Embed** renders the checkout inside your page, giving more control over the experience. > > See the [SDK documentation](https://github.com/Dintero/Dintero.Checkout.Web.SDK) for a full comparison. > [tab] Redirect > > Send the customer to the Dintero-hosted payment page: > > ```js theme={null} > import { redirect } from "@dintero/checkout-web-sdk"; > > redirect({ > sid: "T12345678.xxxxxxxxxxxxxxxxxxxx", > }); > ``` > > Or redirect directly to the session `url` from step 3. > [tab] Embed > > Embed the checkout in your page: > > ```html theme={null} >
> ``` > > ```js theme={null} > import { embed } from "@dintero/checkout-web-sdk"; > > await embed({ > container: document.getElementById("checkout-container"), > sid: "T12345678.xxxxxxxxxxxxxxxxxxxx", > }); > ``` Use [test data](/docs/checkout/checkout-testdata) to complete a test payment. ## Step 5: Handle the result After payment, Dintero notifies you through two channels: | Channel | How | Reliable? | Use for | | - | - | - | - | | **callback_url** | GET to your server | Yes (retried up to 20 times) | Verify payment, fulfill order | | **return_url** | Customer redirect | No (browser may close) | Show confirmation page | > [!WARNING] > > Always verify the transaction via the callback. The redirect is not guaranteed. See [After payment](/docs/checkout/after-payment) for transaction statuses and handling. ## What's next > [card] [Express Checkout](/docs/checkout/express) > > Skip address forms for faster conversions. > [card] [Embed vs redirect](/docs/checkout/embedVredirect) > > Compare integration approaches. > [card] [Test data](/docs/checkout/checkout-testdata) > > Test cards and sandbox scenarios. # Dintero Checkout Web SDK Source: https://docs.dintero.com/docs/checkout/sdk/checkout-web-sdk Use the @dintero/checkout-web-sdk in your frontend to embed the Dintero Checkout, listen for session events, and customize the in-page payment flow. Use this SDK in your frontend application to embed one or more discounts from the Dintero Discount Service in your webpage. ### Installation ```node theme={null} npm install @dintero/checkout-web-sdk ``` ### Inline HTML JavaScript example - Using the SDK for an embedded checkout (minimal) When payment is completed, the SDK will redirect the end user to the return_url defined in the session. ```html theme={null} ``` ### Installation For more detailed information about installation click [here](https://github.com/Dintero/Dintero.Checkout.Web.SDK) # Dintero Discount SDK Source: https://docs.dintero.com/docs/checkout/sdk/discount-sdk Embed discounts from the Dintero Discount Service in your web pages with the @dintero/discounts-web-sdk frontend library and predefined components. Use this SDK in your frontend application to embed one or more discounts from the Dintero Discount Service in your webpage. ### Installation ```node theme={null} npm install @dintero/discounts-web-sdk ``` ### Inline HTML JavaScript example - Getting a list of discounts with API access In this example the SDK will try to fetch data from the discount service. Make sure to configure the plugin with an API client that only has grants giving access to the public:discounts scope. ```html theme={null} ``` ### Installation For more detailed information about installation click [here](https://github.com/Dintero/Dintero.Discounts.Web.SDK) # Dintero Node SDK Source: https://docs.dintero.com/docs/checkout/sdk/node-sdk Call the Dintero API from server-side JavaScript with the @dintero/node-sdk package: manage authentication, sessions, and payment operations from Node. The Dintero Node SDK provides convenient access to the Dintero API from applications written in server-side JavaScript. ### Installation Install the package with: ```sh theme={null} npm install @dintero/node-sdk # or yarn add @dintero/node-sdk ``` ### Usage To use the Dintero Node.js SDK, you will need to configure it with your API credentials that can be created in the Dintero Backoffice. These credentials include the Client ID, Client Secret, and Audience, which are required for authenticating your requests to the Dintero API. ### Example: Client setup You first need to create a client with the required credentials: ```ts theme={null} import { createClient } from "@dintero/node-sdk"; const client = createClient({ clientId: 'your_client_id', // Replace with your actual client ID clientSecret: 'your_client_secret', // Replace with your actual client secret audience: 'https://api.dintero.com/v1/accounts/your_account_id', }); export default client; ``` ### Example: Session profile ```ts theme={null} import { createClient } from '@dintero/node-sdk'; const client = createClient({ clientId: 'your_client_id', // Replace with your actual client ID clientSecret: 'your_client_secret', // Replace with your actual client secret audience: 'https://api.dintero.com/v1/accounts/your_account_id', }); const sessionProfileResponse = await client.checkout.POST('/sessions-profile', { method: 'POST', body: { url: { return_url: 'https://example.com', // Replace with actual return URL }, order: { amount: 1000, currency: 'NOK', items: [ { id: 'item1', line_id: 'line1', description: 'Item 1', amount: 1000, quantity: 1, vat_amount: 0, vat: 0, eligible_for_discount: false, }, ], partial_payment: false, merchant_reference: 'ref123', // Replace with actual merchant reference }, profile_id: 'profile123', // Replace with actual profile ID }, headers: { 'Content-Type': 'application/json', 'Accept': 'application/json', }, }); console.log('Session Profile Response:', sessionProfileResponse.data); ``` ### Example: Fetching settlement ```ts theme={null} import { createClient } from '@dintero/node-sdk'; const client = createClient({ clientId: 'your_client_id', // Replace with your actual client ID clientSecret: 'your_client_secret', // Replace with your actual client secret audience: 'https://api.dintero.com/v1/accounts/your_account_id', }); const settlementsResponse = await client.core.GET(`/accounts/${client.accountId}/settlements`, { method: 'GET', headers: { 'Accept': 'application/json', }, } ); console.log('Settlements Response:', settlementsResponse.data); ``` ### Installation For more detailed information about installation click [here](https://github.com/Dintero/Dintero.Node.SDK) # Dintero Python SDK Source: https://docs.dintero.com/docs/checkout/sdk/python-sdk Interact with the Dintero Checkout API from Python with the dintero PyPI package, including helpers for authentication, sessions, and payment management. With the Dintero Python SDK you can easily interact with the Dintero API to create and manage payments through the Checkout API, and in the future also use the many other APIs we've got. ### Installation ```pip theme={null} pip install --upgrade dintero ``` ### Example usage 1. Create an account through [https://onboarding.dintero.com](https://onboarding.dintero.com). 2. Get client credentials from the Dintero Backoffice, see guide. 3. Create a payment profile by going to Dintero Backoffice --> Settings --> Payment Profiles Use your newly created credentials to create a session: ```py theme={null} from dintero import Dintero account_id = 'T12345678' client_id = '72e023b1-aeda-498e-b141-4669528c44b9' client_secret = '125f9f0a-e240-4bfd-be57-0086343bf0e4' profile_id = 'T12345678.46dP6T4F1mUXYPeYKYc5Gj' dintero = Dintero( account_id, client_id, client_secret) checkout = dintero.checkout() session_info = checkout.create_session({ "url": { "return_url": "https://example.com/accept", "callback_url": "https://example.com/callback" }, "order": { "amount": 29990, "currency": "NOK", "merchant_reference": "string", "items": [ { "id": "chair-1", "line_id": "1", "description": "Stablestol", "quantity": 1, "amount": 29990, "vat_amount": 6000, "vat": 25 } ] }, "profile_id": profile_id }) print(session_info) ``` ### Installation For more detailed information about installation click [here](https://github.com/Dintero/Dintero.Python.SDK) # Shipping address callback Source: https://docs.dintero.com/docs/checkout/shipping-address-callback Update the shipping options in Dintero Checkout when the customer changes their shipping address, using either a backend callback endpoint or the Web SDK onAddressCallback function. Updating the shipping options presented to the end customer when they add or change their shipping address in the checkout can be implemented either via a **backend callback endpoint** or via a **frontend callback function** when using the [Dintero Web SDK]. ## Updating shipping options via backend callback endpoint > [!NOTE] > > If you use the \[Dintero Web SDK] and provide an `onAddressCallback` function, the checkout does not call `express.shipping_address_callback_url`. See [Updating shipping options via frontend callback function](#updating-shipping-options-via-frontend-callback-function). When there are changes in the shipping address in the checkout, a callback is sent from Dintero's services to the endpoint that you have specified in `session.express.shipping_address_callback_url` with an updated order including the new address. The webshop should update the webshop state/order with the new shipping address, and return a list of available [shipping options](/docs/checkout/shipping-options) for the given shipping address. Link to [the API specification for the callback endpoint](/api-reference/example-session-callbacks/example_shipping_address_callback_url). Note that the request body is what *Dintero* will post to your endpoint and the response is what *your endpoint* returns back to Dintero. If the checkout is embedded, the [Dintero Web SDK] will call **onSession** whenever the session is updated, with the event **SessionUpdated**. ### Compatibility with "one click" Apple Pay and Google Pay In order to support one click express payments via Apple Pay and Google Pay your endpoint must support returning shipping options when the `session.order.shipping_address` in the request body from Dintero’s systems contains only `country` and `postal_code`. ## Troubleshooting the backend callback ### If correction item is added to the order If the implementation has problems with items of the type correction, you might have problems with the shipping address callback. ```json title="Item with correction" theme={null} { "id": "correction-mc7nt6LjqgCejGGLNHpFMq", "amount": -10000, "line_id": "correction-mc7nt6LjqgCejGGLNHpFMq", "quantity": 1, "description": "Correction" } ``` This can happen when handling the callback and responding with an updated order with the wrong `order.amount`. To solve this, make sure that `order.amount` contains the amount from the shipping option which is currently chosen. #### Example If the callback contains the following: ```json theme={null} { "order": { "items": [ { "id": "item-1", "line_id": "item-1", "amount": 10000, "vat": 25, "vat_amount": 2000, "quantity": 1 } ], "amount": 20000, "vat_amount": 4000, "currency": "NOK", "shipping_option": { "id": "shipping", "line_id": "shipping", "amount": 10000, "vat": 25, "vat_amount": 2000 } } } ``` then, if the order is not changed, the response needs to contain the `10000` from the request `order.shipping_option.amount`: ```json theme={null} { "order": { "items": [ { "id": "item-1", "line_id": "item-1", "amount": 10000, "quantity": 1, "vat": 25, "vat_amount": 2000 } ], "amount": 20000, "vat_amount": 4000, "currency": "NOK" } } ``` If the tax of the item has changed from 25% to 20% you should still provide the same amount from the callback payload. If the shipping option price has changed, we will adjust the total price of the whole order when we choose the shipping option from the new list of shipping options. ```json theme={null} { "order": { "items": [ { "id": "item-1", "line_id": "item-1", "amount": 9600, "quantity": 1, "vat": 20, "vat_amount": 1600 } ], "amount": 19600, "vat_amount": 3600, "currency": "NOK" } } ``` > [!TIP] > > The use-cases for when the order changes when the address is changed are: > > * The new address is in another country or state, and the tax is different for the new location > * Other, less probable ones (e.g. if the customer is from a certain location, they have to buy a specific item) > > If these use cases don't apply to you, it's best to respond to the callback with just the new shipping options. ## Updating shipping options via frontend callback function This only applies when the checkout is embedded and the embedding site is using the [Dintero Web SDK]. It is not available when the checkout is opened with `redirect()`. In pop-out mode the embedding page handles the callback, not the pop-out window. If the `onAddressCallback` function is provided, the checkout will not perform the machine to machine address update callback defined in the session at `express.shipping_address_callback_url`. Instead the SDK runtime has to handle the address update flow. The `onAddressCallback` function is invoked when an end user submits their address details (the shipping and billing addresses) in an embedded Checkout Express session. The callback function is invoked with an updated session that is not yet persisted in the Dintero backend. The checkout will be locked and payment will be paused until the provided callback function is called, or `checkout.submitAddressCallbackResult` is called with the result. The function receives an event with the event `type`, the updated `session`, and the `callback` used to return the result. When `onAddressCallback` is invoked you will have to perform a **server-to-server** [session update](/api-reference/session/checkout_session_put) with shipping options or other details that have changed. Once the session has been updated you need to call the provided callback function with a result. When the session has been updated successfully, return a successful result: ```js theme={null} { success: true } ``` If the session update failed, return the result with an error message: ```js theme={null} { success: false, error: "" } ``` ```js theme={null} onAddressCallback: function(event, checkout, callback) { // Perform a server-to-server session update getShippingOptionsForAddressAndUpdateSession(event.session).then(() => { callback({ success: true, }); }).catch((err) => { callback({ success: false, error: toErrorMessage(err), }); }); }, ``` > [!NOTE] > > When implementing the `onAddressCallback`, there is no need to manually lock the session and refresh it as described in [Updating a checkout session](/docs/checkout/updating-session). The checkout will automatically lock the payment and refresh the session when the `callback` function is used to return a result. If your `onAddressCallback` function throws, the SDK returns `{ success: false, error: "Address callback runtime error" }` on your behalf so the checkout is not left waiting. See also the [onAddressCallback section](https://github.com/Dintero/Dintero.Checkout.Web.SDK#handling-checkout-express-address-updates-using-the-onaddresscallback) in the [Dintero Web SDK] documentation. [Dintero Web SDK]: https://github.com/Dintero/Dintero.Checkout.Web.SDK # Shipping options in Checkout Express Source: https://docs.dintero.com/docs/checkout/shipping-options Configure shipping options in Dintero Checkout Express with id, line_id, amount, and operator fields so customers can pick their preferred delivery option. Checkout Express lets the merchant list multiple shipping options so their customers can select their preferred shipping option. The shipping options will be listed in the order they appear in the `express.shipping_options` array. Each shipping option needs a minimum set of required declared properties: ```json theme={null} { "id": "group-id", "line_id": "unique-shipping-id", "amount": 10000, "operator": "shipping-provider-name", "title": "Home delivery" } ``` * `id`: ID of the shipping option product. This ID does not have to be unique as it will be used by Checkout to group together shared shipping option products that deliver to same address at different time slots, or shipping options that have the same name and amount but different `pick_up_address`. * `line_id`: The unique ID of the specific configuration of the shipping option product. This will be used to identify the selected shipping option in the order. * `amount`: The monetary amount of the shipping option, including VAT and discounts in the smallest unit of the session currency. * `operator`: Name of the company that provides shipping service. * `title`: The title of the shipping option. For example, "Standard home delivery". Shipping options can be configured in several ways allowing for flexible configuration and appearance in the UI. The following documentation will go through each possible addition to the shipping option, in which all of them are optional but contribute to a better checkout experience for the customer. ```json theme={null} { ... "countries": ["NO", "SE"], "vat_amount": 2500, "vat": 25, "description": "Fastest delivery service to your doorstep", "delivery_method": "delivery", "operator_product_id": "shipping-product-id", "eta": { "working_days": [1,5] }, "time_slot": { "starts_at": "2025-02-06T12:00:00+02:00", "ends_at": "2025-02-10T17:00:00+02:00" }, "pick_up_address": { "first_name": "John", "last_name": "Doe", "address_line": "Address", "address_line_2": "Address 2", "co_address": "Land Lord", "business_name": "Business name", "postal_code": "0349", "postal_place": "Oslo", "country": "NO", "phone_number": "+47XXXXXXXX", "email": "email@example.com", "latitude": 0, "longitude": 0, "comment": "Comment about pick up address", "organization_number": "XXXXXXXX", "organization_type": "XX", "customer_reference": "Ref.", "cost_center": "Cost center specification", "website_url": "http://example.com", "opening_hours": { "open_now": true, "periods": [ { "opens_at": "08:00", "closes_at": "16:00", "day_of_week": 1 } ], "timezone": "Europe/Oslo" }, "distance": 0 }, "metadata": { "operator_dest": "XAB1239", "number_x": 1921 }, "environmental_data": { "description": "Fossil free", "details": [ { "label": "Carbon offset", "value": "1KG CO2" } ] }, "thumbnail_url": "http://example.com", "pay_in_store": { "type": "full" }, "fee_split": { "type": "proportional", "destinations": [ "string" ] }, "splits": [ { "payout_destination_id": "seller-id", "amount": 29700 } ] } ``` ### Providing more details to a shipping option #### Delivery method `delivery_method` states what type of delivery the shipping option product is and should be supplemented with additional details such as `pick_up_address`, `eta` and/or `time_slot` for optimal user flow. ```json theme={null} { "delivery_method": "delivery" | "pick_up" | "unspecified" | "none" } ``` #### Estimated time of arrival `eta` can be used to give the shipping option a time estimate. It can be specified as a date-time range by setting the `starts_at` and `ends_at` date-times. If the dates in `starts_at` and `ends_at` are different, the checkout will only show the dates, if the dates are the same the checkout will also show the time specified. ```json theme={null} { "eta": { "starts_at": "2021-09-01T00:00:00Z", "ends_at": "2035-09-01T00:00:00Z" } } ``` ![Time estimate](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/checkout-shipping-option-eta-time.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=bbb1b05dff0e32a9ead2bf1baad2776e) Or a working days estimate: ```json theme={null} { "eta": { "working_days": [1, 2] } } ``` ![Working days estimate](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/checkout-shipping-option-eta-working-days.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=0ccf6c34b6853a2c32922a94966ef20f) Or an estimated arrival/shipping on the day of the week, or in combination: ```json theme={null} { "eta": { "arrival_day_of_week": 2, "shipping_day_of_week": 2, "working_days": [1, 2] } } ``` ![Combinations](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/checkout-shipping-option-eta-combinations.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=1a971b42db24a12bdf214ba1d0963f00) `working_days` can be used to describe the lowest estimated amount of working days and the highest estimated amount of working days needed for the shipping process. The array corresponds to the display of `n-n` in Checkout. A range of `[0, 0]` will correspond to a shipment that occurs today or next possible working day. `(arrival|shipping)_day_of_week` can be used when shipment or arrival of items occurs during a day of the week. The value corresponds to the order of the day in a week by European conventions. For instance, a shipping option that ships on fridays would have `shipping_day_of_week` set to `5` as Friday is the fifth day in a week going from Monday to Sunday. `starts_at` and `ends_at` can be used to provide an absolute time estimate of the shipping option. #### Time slot `time_slot` provides the shipping option with a specified time of delivery to the customer. ```json theme={null} { "time_slot": { "starts_at": "2021-09-01T00:00:00+02:00", "ends_at": "2035-09-01T00:00:00+02:00" } } ``` #### Pick up address `pick_up_address` can be used to provide address details of where the items will be delivered by a shipping option. All of the fields are optional to include, but provide sufficient context to the shipping option. ```json theme={null} { "pick_up_address": { "first_name": "John", "last_name": "Doe", "address_line": "Address", "address_line_2": "Address 2", "co_address": "Land Lord", "business_name": "Business name", "postal_code": "0349", "postal_place": "Oslo", "country": "NO", "phone_number": "+47XXXXXXXX", "email": "email@example.com", "latitude": 59.9500157, "longitude": 10.7663589, "comment": "Comment about pick up address", "organization_number": "XXXXXXXX", "organization_type": "XX", "customer_reference": "Ref.", "cost_center": "Cost center specification", "website_url": "http://example.com", "opening_hours": { "open_now": true, "periods": [ { "opens_at": "08:00", "closes_at": "16:00", "day_of_week": 1 } ], "timezone": "Europe/Oslo" }, "distance": 1.5 } } ``` #### Environmental data A shipping option can include details on how big of an environmental impact the shipping process will be by declaring `environmental_data`. This will be shown in Checkout within a tooltip beneath the label "Climate smart". ```json theme={null} { "environmental_data": { "description": "Carbon neutral delivery", "details": [ { "label": "Carbon offset", "value": "0.5 kg CO2e" }, { "label": "Trees planted", "value": "3" } ] } } ``` ![Environmental details](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/checkout-shipping-option-climate.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=a1f35457072c316a10745e0589f1586b) #### Shipping operator branding Checkout by default provides iconography for the most common shipping operators, but if there's a need for a custom logo on the shipping option then `thumbnail_url` can be used. ##### List of operators in which iconography is provided by Checkout: | Operator | Value | | - | - | | Posten | `posten` | | Bring | `bring` | | Helthjem | `helthjem` | | Postnord | `postnord` | | Gordon | `gordon` | | DHL | `dhl` | | UPS | `ups` | | FedEx | `fedex` | | DB Schenker | `dbschenker` | | Dachser | `dachser` | | Budbee | `budbee` | | PorterBuddy | `porterbuddy` | | TNT | `tnt` | | Instabox | `instabox` | ### Grouping shipping options Similar shipping options can be grouped to improve the user experience. To group multiple shipping options the following requirements need to be met: * All items within a single group has to use the same values for `id`, `title`, `amount` and `delivery_method` and `operator`. * The `delivery_method` has to be either `delivery` or `pick_up`. * If `delivery_method` is set to `delivery` a `time_slot` needs to be set for each option in the group. * If `delivery_method` is set to `pick_up` a `pick_up_address` needs to be set for each option in the group. #### Grouped delivery options with different time slots See also the [section on time slots](#time-slot) on how to specify a time slot. ![Shipping options time slot group](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/checkout-shipping-options-group-by-time-slot.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=1fe088c202812a50f4b8802158e4012a) #### Grouped pick up options with different pick up addresses See also the [pick up address example](#pick-up-address) for more information on what properties are supported. ![Shipping options pick up group](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/checkout-shipping-options-group-by-pick-up.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=d803fd012aab33ce52bb1d2354d2e953) ### Restricting a shipping option to a set of countries A session can contain multiple shipping options catered towards different countries and still provide only the relevant shipping options available for the customer. For example, to make a shipping option only appear for Norwegian customers, add the following to the configuration: ```json theme={null} { "countries": ["NO"] } ``` This will restrict the shipping option to only be available for Norwegian customers when entering Checkout. Other shipping options that do not have this specified are not affected. Multiple countries can also be added. In the following example, the shipping option will only be available to Norwegian and Swedish customers. ```json theme={null} { "countries": ["NO", "SE"] } ``` ### Splitting the payment of a shipping option Similar to how items behave with `splits`, the same applies for a shipping option. [Instructions for using `split`](/docs/checkout/split-payment/creating-split-session) ### Pay in store [Instructions for `pay_in_store`](/docs/checkout/pay-in-store) ### Sessions without shipping options or hiding the shipping option The shipping option selection can skipped if the order does not have shipping, like a service or a digital product. This can be achieved by setting the `shipping_mode` on the session in the `session.express` object to `shipping_not_required ` and set the `shipping_options` to an empty array. ```json theme={null} { ..., "express": { "shipping_options": [], "shipping_mode": "shipping_not_required" } } ``` Another option for hiding or not displaying the shipping option in the checkout is to create a single shipping option that has the `type` set to `none` and the `amount` set to zero. ```json theme={null} { "id": "hidden", "line-id": "single-hidden-shipping-option", "title": "Will not show up in the checkout", "type": "none", "amount": 0, "operator": "none" } ``` ### Dynamic and static shipping options The shipping options are static if the `shipping_address_callback_url` is not defined. It has to be omitted from the json payload, so setting it to undefined (not valid json) or null or an empty string is not allowed. ```json theme={null} { ..., "express": { "shipping_options": [...] } } ``` Use the `shipping_address_callback_url` to make the list shipping options in the checkout dynamic based on the customers address. A request will be sent to the callback when the end user submits or changes their address in the checkout. If the current address of the customer is not supported by the merchant (or their logistics operators) return an empty list to inform the checkout that delivery to the customers address is not possible. For more information continue to [the docs shipping callbacks documentation](/docs/checkout/shipping-address-callback) and [the API spec for the address update](/api-reference/example-session-callbacks/example_shipping_address_callback_url). ### Specifying a default shipping option The Checkout will automatically select the first shipping option in the list of available shipping options if the selected shipping option is not specified in the `session.order`. If a specific shipping option should be selected, add the shipping option in `session.order`: ```json theme={null} { "order": { ..., "shipping_option": { ..., "line_id": "shipping-line-id" } }, "express": { "shipping_options": [ ..., { ..., "line_id": "shipping-line-id" } ] } } ``` ### Multiple shipments If the order contains multiple shipments please see the [the guide for how to handle multiple shipments](/docs/checkout/shipping-options-multiple-shipments). # Multiple shipments in Checkout Express Source: https://docs.dintero.com/docs/checkout/shipping-options-multiple-shipments Configure Checkout Express orders that ship in multiple shipments using shipment_id, shipment_items, and a top-level shipping_option with multiple shipments. For Checkout Express orders with multiple shipments there are some extra considerations to take into account. Please read [the single shipment shipping option guide](/docs/checkout/shipping-options) before continuing the guide for handling multiple shipments. Notable changes from the single shipment flow: * The **express.shipping_options** must include a **shipment_id** that is used to group the shipping options per shipment. * The **express.shipping_options** must include **shipment_items** that describes what items belong to a shipment. * The **order.shipping_option** is *a single top-level shipping option* that has multiple **shipments**. ### What it looks like ![Checkout Express with multiple shipments](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/checkout-shipping-option-multi-shipment.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=2769cc8d4c52c7bbcb82e1ed9d6de446) ### Express shipping options For shipping options in **express.shipping_options** and shipping options returned by the optional **express.shipping_address_callback_url** endpoint. When the order contains multiple shipments each shipping option has to contain a **shipment_id** that is used for grouping the options for that shipment. The shipping options must also contain list of **shipment_items** that specify the items (and optionally quantities) that are included in the shipment. The **shipment_items** list is used to determine which items are included in the shipment and is displayed in the checkout. All shipping options that share the same **shipment_id** should have the same **shipment_items** list. Each multi shipment shipping option needs a minimum set of required declared properties: ```json theme={null} { "id": "group-id-1", "line_id": "unique-shipping-id-1", "amount": 10000, "operator": "shipping-provider-name", "title": "Home delivery", "shipment_id": "shipment-1", "shipment_items": [ { "line_id": "line-1", "quantity": 1 }, { "line_id": "line-2", "quantity": 2 } ] } ``` ### The shipping option in the order object The shipping option found in the **order.shipping_option** is *a single top level shipping option* that contains multiple **shipments**. The shipment array must contain a single shipping option per **shipment_id** found in **express.shipping_options**. There must be two or more shipping options in the shipments array, if you only have a single shipment use [the single shipment flow instead](/docs/checkout/shipping-options). Example top-level shipping option for an order with multiple shipments: ```json theme={null} { "id": "multi_shipment", "title": "Multiple shipments", "amount": 40000, "line_id": "multi_shipment", "operator": "", "shipments": [ { "id": "group-id-1", "line_id": "unique-shipping-id-1", "amount": 10000, "operator": "Bring", "title": "Home delivery", "shipment_id": "shipment-1", "shipment_items": [ { "line_id": "line-1", "quantity": 1 }, { "line_id": "line-2", "quantity": 2 } ] }, { "id": "group-id-2", "line_id": "unique-shipping-id-2", "amount": 30000, "operator": "DHL", "title": "Express delivery", "shipment_id": "shipment-2", "shipment_items": [ { "line_id": "line-3", "quantity": 1 } ] } ] } ``` ## After payment has been completed The resulting transaction will contain the top-level multi shipment shipping option, but we will append a single item per shipment to the **order.items** in the resulting transaction so that the shipments can be captured and refunded separately. # Limit checkout to a single payment type Source: https://docs.dintero.com/docs/checkout/show-payment-type Use the show_payment_type query parameter to display only specific Dintero Checkout payment methods, ideal for native wallets like Apple Pay or Google Pay. Sometimes, you may want to create a session with multiple payment methods, but only display one specific payment type to the end user during checkout. **Typical use cases:** * Sessions containing both platform-native payment options (e.g., Apple Pay, Google Pay) and payment types requiring an embedded web UI (e.g., credit card payments). ## How to limit payment types in Checkout To restrict the checkout to specific payment types, append the `show_payment_type` query parameter when embedding or redirecting to the checkout page. You can specify one or more payment types. **Example:** To show only credit card payments: ```text theme={null} https://checkout.api.dintero.com/v1/view/{session_ids}/?show_payment_type=dintero_psp.creditcard ``` ## Minimal UI mode To embed a minimal version of Dintero Checkout, ideal for showing a single payment option in web UI (like a card payment form), append a `ui` query parameter set to `inline` to the session link. **Example:** ```text theme={null} https://checkout.api.dintero.com/v1/view/{session_id}/?show_payment_type=dintero_psp.creditcard&ui=inline ``` # Activate Dintero Payout Source: https://docs.dintero.com/docs/checkout/split-payment/activate-payout Step-by-step guide for activating Dintero Payout for your account so you can settle funds to your company and onboard sellers for split payouts. In order to pay money to your company, activate Dintero Payout for your account. To do this, Dintero needs to know a couple of things about your company first, so there's a small form to fill out, and a couple of questions we need to ask. Don't worry, this process is usually fast. To activate Dintero Payout, follow these steps: 1. Start activating payout Go to **Settings** → **Sellers** and click **Enable Dintero Payout** ![Dintero Payout section with the Enable Dintero Payout button](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/backoffice/split-payment/activate-payout/activate-payout-step-1.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=9593c5ad82a8856789a7f0589304824e) 2. Fill out your bank account information Fill out your bank account number and its currency, and press **Enable Dintero Payout** to go further. ![Enable Dintero Payout dialog with account number and currency fields](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/backoffice/split-payment/activate-payout/activate-payout-step-2.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=7bb86e31956fce727d3c1d5b6024be00) 3. Open the agreement A form has been created for you to fill out. We try to prefill most of the information in here, but there are some choices to make. Press **Open the Dintero Payment agreement** to go there. ![Dintero Payout section with the Open the Dintero Payment agreement button](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/backoffice/split-payment/activate-payout/activate-payout-step-3.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=0221802e988c678476687ba1e4757ed2) 4. Fill out the form and submit your declaration Once all the info is filled out correctly, submit the form. ![Submit my declaration button at the end of the agreement form](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/backoffice/split-payment/activate-payout/activate-payout-step-4.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=d91e39a78ce77a0522c8e62b486d7a03) 5. Sign the agreement electronically An email will be sent to the signatories specified in the company declaration with a link to sign electronically. 6. Wait for approval Our KYC-department will take a look at the data and evaluate your application. You will be contacted once the approval is completed. ![Thank you page confirming the declaration was received](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/backoffice/split-payment/activate-payout/activate-payout-step-5.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=02d78ad0e968b4b5117bf2936aeabaa7) 8. You can now add sellers # Add sellers and payout destinations Source: https://docs.dintero.com/docs/checkout/split-payment/add-payout-destinations Onboard merchants as sellers under Dintero Payout, configure their payout destinations, and run the approval flow that unlocks split payments on your platform. Once your company is approved for Dintero Payout, you can start the process adding your merchants as sellers. You can choose to do this part from Backoffice, or through the API. ## Onboarding your merchants from Backoffice Once again, go to **Settings** → **Sellers**. Here, you will find a new button **Add new Seller** . 1. Fill out preliminary info about your merchant. > [tab] Company > > When onboarding a company you will need to provide the country, organization number, currency and seller id. > > ![Add Seller form in Backoffice with the Company tab selected](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/backoffice/split-payment/payout-destinations/add-company-seller.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=5d0eded9992ee21276eec83f6ea0914f) > [tab] Individual > > When onboarding an individual you will need to provide the country, the name of the individual, currency and seller id. > > ![Add Seller form in Backoffice with the Individual tab selected](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/backoffice/split-payment/payout-destinations/add-individual-seller.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=0ccfe60a7dcf0a50cfaf9ec19d527073) 2. Once filled out, press Continue and you will get a **link** to send to your **merchant**. ![Add new Payout Destination dialog showing the contract link](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/backoffice/split-payment/payout-destinations/add-payout-destination-step-2.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=2921afa386edb7a3f11d0a8aba52a73d) ## Onboarding your merchants through the API 1. Fill out preliminary info about your merchant. Use [New seller approval](/api-reference/approvals/aid_management_settings_approvals_payout_destinations_post) to fill out information about the merchant. The `type` field decides which fields you send: > [tab] Company > > Set `type` to `company`, or leave it out. `organization_number` and `country_code` are required. > [tab] Individual > > Set `type` to `individual` and describe the person in the `individual` object. The object accepts `name`, `birth_date`, > `phone_number`, `email`, address fields and `citizenships`. All fields in the object are optional. Each `citizenships` > entry requires `country` and `social_security_number`. `payout_destination_id`, `payout_reference` and `bank_accounts` are required for both types. The rest of the flow is the same. 2. Receive a link to send to your merchant. The link will be in the response under **links** with `rel=contract_url`. While the merchant has not yet completed the declaration form and signed the agreement, the approval has `case_status=WAITING_FOR_DECLARATION`. ## Handing over to your merchant Now, take this link and send it to your merchant. This link will take your merchant to a similar KYC form to yours. If a `form_submitter` email was provided when creating the approval, the merchant will be notified via email. ### Reminder emails If the form is not completed (unsigned or undeclared), reminder emails are automatically sent on the following schedule: 1. 24 hours after the initial notification 2. 2 days after 3. 1 week after 4. 2 weeks after 5. 4 weeks after Once they've submitted their company declaration form and signed the agreement electronically our KYC department will take a look at the data and evaluate your application. ## Seller approval To know when the Seller is approved, you can create a webhook from **Settings** → **Webhooks** → **Add webhook** and choose **approval_payout_destination_update**. > [!NOTE] > > See [webhooks approval_payout_destination_update](/api-reference/example-management-auth-events/example_approval_payout_destination_update_event) for > example of data that will be sent to the webhook Consider the Seller approved when the seller approval has been updated to `case_status=ACTIVE`. You can also poll the endpoint [List seller approvals](/api-reference/approvals/aid_management_settings_approvals_payout_destinations_get) to see when the destinations are approved. Once the seller is approved, you can start creating sessions with splits. ### Testing seller approval In test mode (account IDs prefixed with `T`), you can skip the declaration form and KYC review: * Set `payout_destination_description` to `AUTO_APPROVE`, `AUTO_DECLINE` or `AUTO_WAITING_FOR_SIGNATURE`. See [Auto-approve sellers](/docs/checkout/testdata/approvals/auto-approve). * Use a test bank account number in `bank_accounts`. See [Test bank accounts](/docs/checkout/testdata/approvals/bank-accounts). > [!NOTE] > > You can technically create sessions with splits before the sellers being approved, but there is no guarantee that they will be approved. > > In the case that an unknown or unapproved seller is used, the plattform merchant will have to deal with the matter manually. # Create a session with split payments Source: https://docs.dintero.com/docs/checkout/split-payment/creating-split-session Create Dintero Checkout sessions with split payouts that route funds to multiple sellers, for marketplaces, platform fees, and multi-merchant transactions. With Dintero Payout, you can split the funds between any number of sellers. For example, when a customer pays on your platform, you can split the funds so that a part goes to your own seller as platform fee and the sale amount goes to the sales location seller. ## Providing split information You can provide split information: * When [creating](/api-reference/session/checkout_session_profile_post) new payment session * When [capturing](/api-reference/transactions/transactions_id_capture_post) the payment transaction * When [refunding](/api-reference/transactions/transactions_id_refund_post) the payment transaction To split the payment, you will need to include the **splits** array in the session order items. For each split object in the array, you need to specify the following fields: * **`payout_destination_id`**: The destination that will receive the split * **`amount`**: The split amount For example, a customer pays for goods for 499,90 NOK, you can split the payment such that: * 399,90 NOK goes to the merchant * 70,00 NOK goes to the platform * 30,00 NOK is a donation to a charity > [!NOTE] > > Dintero supports as many sellers as you need, but there might be limitations based on item amounts. ```json theme={null} { "order": { "items": [ { "splits": [ { "payout_destination_id": "merchant", "amount": 39990 }, { "payout_destination_id": "platform", "amount": 7000 }, { "payout_destination_id": "charitable_organization", "amount": 3000 } ] } ] } } ``` ### Platforms Platforms must specify the merchant of record of the transaction. > [!NOTE] > > You will be informed during onboarding to Dintero about whether you are a marketplace or platform. To specify the merchant of record, include `store.payout_destination_id` in the order: ```json theme={null} { "order": { "store": { "id": "my-store-id", "payout_destination_id": "merchant" } } } ``` ## Validating split information The Checkout service only validates the format of the split data. The seller in the splits will **not** be validated. If you provide split data with a seller that does not exist or the seller is not approved for payout, the payout for the destination will be postponed until the issue with the seller has been resolved. ## Providing fee split information The default behaviour when splits are used is to let the fees be shared proportionally with all split destinations. The default behaviour can be overridden by including `fee_split` when setting **splits** ### Override default fee split Example under shows how a split destination can be configured to handle the fees. ```json theme={null} { "order": { "items": [ { "splits": [ { "payout_destination_id": "merchant", "amount": 39990 }, { "payout_destination_id": "platform", "amount": 7000 }, { "payout_destination_id": "charitable_organization", "amount": 3000 } ], "fee_split": { "type": "proportional", "destinations": [ "platform" ] } } ] } } ``` > [!NOTE] > > Sellers that are excluded from fees will receive the whole amount when the payout is settled. ### Fee-only destinations Use `fee_split.type: "equal_fee_only"` when a destination should only cover fees and never receive any income from the order. Unlike `proportional`, `equal_fee_only` destinations must not be included in **splits** - they accumulate fee debt without ever being paid out a share of the sale. If multiple destinations are listed, the fee is divided equally between them. > [!NOTE] > > `equal_fee_only` must be enabled on your account before you can use it. > Contact Dintero support to enable it. > > `proportional` is always allowed and needs no configuration. In the example below, the destinations listed in `items[].splits` receive the amount in its entirety. `platform` covers the entire fee but does not appear in `splits`, so it receives no income from the order. ```json theme={null} { "order": { "items": [ { "splits": [ { "payout_destination_id": "receiver_a", "amount": 29900 } ], "fee_split": { "type": "equal_fee_only", "destinations": [ "platform" ] } }, { "splits": [ { "payout_destination_id": "receiver_b", "amount": 19900 } ], "fee_split": { "type": "equal_fee_only", "destinations": [ "platform" ] } } ] } } ``` ## Full example of creating a session When put together, we can call [https://api.dintero.com/v1/accounts//payments/sessions-profile](/api-reference/session/checkout_session_profile_post) with a payload with the following content. If you want non-standard fee splits, see "Override default fee split" above. ```json theme={null} { "url": { "return_url": "https://example.com/accept", "callback_url": "https://example.com/callback?method=GET", "merchant_terms_url": "https://example.com/terms.html" }, "customer": { "email": "john.doe@example.com", "phone_number": "+4799999999" }, "order": { "amount": 49990, "currency": "NOK", "vat_amount": 6000, "items": [ { "id": "item_01", "line_id": "1", "description": "Stablestol", "quantity": 1, "amount": 49990, "vat_amount": 9998, "vat": 25, "splits": [ { "payout_destination_id": "merchant", "amount": 39990 }, { "payout_destination_id": "platform", "amount": 7000 }, { "payout_destination_id": "charitable_organization", "amount": 3000 } ] } ], "merchant_reference": "merchants_unique_id" }, "profile_id": "default" } ``` > [!NOTE] > > Most new accounts should have the `default` profile_id available. If you have an old account, go [here](/docs/checkout/payment-profiles) to learn how to create one. ## Capture and refund When capturing or refunding a split-payment you can do a full capture or full refund using only the total order amount defined in the session. For full captures and refunds the capture and refund operation will use the splits as defined in the session. If you want to do a partial capture or a partial refund, the operation request body will also need to include the items and the splits for the items that are captured or refunded. It is also possible to use a different split from what is defined in the session when the items with splits are defined in the capture and refund operations. It is also possible to capture and refund asymmetrically, for instance it is possible to define that one party in the split will cover the entire refund. > [!WARNING] > > `fee_split` set on the session is **not** carried over to partial capture or refund operations. When you include `items` and `splits` in a capture or refund request, you must also re-supply `fee_split` for each item. Otherwise the fees fall back to the default behaviour and are shared proportionally across all `payout_destination_id`s in the splits. For example, when partially capturing an item where the platform should cover all fees, include `fee_split` on the item just as you did when creating the session: ```json theme={null} { "amount": 19500, "items": [ { "id": "item_1", "line_id": "1", "quantity": 1, "amount": 19500, "vat": 15, "splits": [ { "payout_destination_id": "farmer-cmmaj13c5004fn601ohx4z2ti", "amount": 18583 }, { "payout_destination_id": "platform", "amount": 917 } ], "fee_split": { "type": "proportional", "destinations": [ "platform" ] } } ] } ``` * [API specification for the capture operation](/api-reference/transactions/transactions_id_capture_post) * [API specification for the refund operation](/api-reference/transactions/transactions_id_refund_post) # Transfer funds between sellers Source: https://docs.dintero.com/docs/checkout/split-payment/fund-transfer Move money from one seller's payout destination to another with the Dintero fund-transfer API, processed asynchronously and shown in the settlement report. ## Initiate fund transfer You can transfer funds between sellers using our fund transfer API. This allows you to move money from one seller’s payout destination to another. > [!NOTE] > > Fund transfers are processed asynchronously, meaning you’ll receive a confirmation that the request was received, but the actual result will appear in the settlement report. ### Ensuring safe retries Each transfer request requires a unique `fund_transfer_id`. This ID ensures idempotent processing, meaning if a request fails (for example, due to a timeout), you can safely retry it using the same `fund_transfer_id`. This avoids accidentally creating duplicate transfers. The API will recognize it’s the same request and not process it again. ### Error codes | Scenario | HTTP Status | Error code | | - | - | - | | Insufficient funds on source payout destination | 400 | `ERR_INSUFFICIENT_FUNDS` | | Payout destination does not have payout interval configured | 400 | `ERR_PAYOUT_INTERVAL_NOT_CONFIGURED` | | The `fund_transfer_id` is already used for a different fund transfer | 400 | `ERR_FUND_TRANSFER_ID_CONFLICT` | For full details, see our [API documentation](/api-reference/payout-destinations/oid_mgmnt_payout_destinations_fund-transfers_post) for fund transfers. ## Testing fund transfers You can test fund transfers using your sandbox account. > [!NOTE] > > Sandbox account IDs use a T prefix. ### Initiate a test fund transfer Initiate a fund transfer using your sandbox `account_id` and credentials. [`POST /payout-destinations/{payout_destination_id}/fund-transfers`](/api-reference/payout-destinations/oid_mgmnt_payout_destinations_fund-transfers_post) ```bash Request wrap theme={null} curl -X POST https://api.dintero.com/v1/accounts/T12345678/payout-destinations/source-pd-123/fund-transfers \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "fund_transfer_id": "6ee80e6583944751997c988ed9f74740", "amount": 499000, "currency": "NOK", "reference": "TF-REF", "destination": { "type": "payout-destination", "account_id": "T12345678", "payout_destination_id": "dest-pd-123" } }' ``` ### Simulating error responses **Insufficient funds** Set `reference` to `"ERR_INSUFFICIENT_FUNDS"` to simulate an HTTP 400 response: ```json theme={null} { "error": { "code": "ERR_INSUFFICIENT_FUNDS", "message": "Insufficient funds" } } ``` **Timeout followed by an idempotent retry** Set `reference` to `"TIMEOUT"` to simulate an HTTP 500 response, i.e. the outcome of the request is unknown. Retrying the identical request using the same `fund_transfer_id` and payload will return the original fund transfer as a successful response. # Split Payout overview Source: https://docs.dintero.com/docs/checkout/split-payment/split-overview Learn how Dintero Split Payout helps marketplaces and platforms onboard sellers and split each Checkout payment across multiple merchants automatically. ## What is Split Payout? Split payout is our solution for marketplaces and platforms looking to easily onboard and pay out to multiple merchants. ## Steps to start splitting payments with Dintero Checkout 1. Activate Dintero Payout for your account 2. Onboard your merchants as Sellers 3. Create sessions with split details 4. Configure reports Let's take a look at how you activate [Dintero Payout](/docs/checkout/split-payment/activate-payout) # Split payout reports Source: https://docs.dintero.com/docs/checkout/split-payment/split-reports Reconcile Dintero Split Payout with per-seller settlement reports in PDF, XML, and CSV plus scheduled custom insight reports and settlement_add webhooks. Dintero provides two types of reports, *Settlement Reports* and scheduled custom *Insight Reports*. #### Settlement reports Settlement reports are created when the settlements are paid out by Dintero Payout, and are available in `.pdf`, `.xml` and `.csv` formats. Every bank account transfer from Dintero to a seller will have its own settlement report. Each item in the [List settlements](/api-reference/settlements/aid_settlements_list) contains a `payout_destination_id` that identifies the seller. You can be notified when a settlement is added by creating a webhook subscription with the `settlement_add` event. * [Settlement Reports API reference](/api-reference/settlements/aid_settlements_list) * [Subscribe to webhooks API reference](/api-reference/subscriptions/aid_source_hooks_post) #### Insight reports The insight reports are created from transaction data and they do not contain any settlement information, but they can be useful for other purposes. Insight reports are based on configurations specifying a data source, filters and interval and the reports for a configuration are created automatically at the *scheduled intervals* eg. **weekly** or **monthly**. To create a report for a seller you need to specify a filter on `payout_destination_id`. * [Create new insight report configuration API reference](/api-reference/report-configuration/aid_report_configuration_post) * [List insight reports API reference](/api-reference/reports/api_reports_metadata_list_get) # Testing split payouts Source: https://docs.dintero.com/docs/checkout/split-payment/testing-split-payments End-to-end testing for Dintero Split Payout (seller creation, sessions, payout, and settlement) using sandbox bank accounts and approval values. Testing split payouts involves testing multiple steps: * Seller Creation * Session creation * Payout and Settlement ## Seller creation To create sellers in Sandbox, go to **Settings** → **Sellers**, select **Test** and click **Add Seller**. * In the **Organization number** field, put the organization number of the seller you want to test. * In the **Seller ID** field, put any value that would represent the seller in your system. It can be anything, but it needs to be unique. For automatic approval, check **Fast-track seller status** and select **Automatic approval** from the dropdown. ![Test seller settings with automatic approval selected in Backoffice](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/backoffice/split-payment/testing/add-seller-automatic-approval.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=f167ff10555b24e3f7fd5cf3b6faefd5) After clicking continue, you will reach this screen: ![Add Seller dialog confirming the fast-tracked seller was submitted](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/backoffice/split-payment/testing/fast-track-receipt.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=199468cbc6d44e24dfed0727f265a1a4) The seller will then be approved automatically within a few minutes. ### Testing with the API It's of course possible to test sellers with the API as well. Follow this [guide](./add-payout-destinations#onboarding-your-merchants-through-the-api), and make sure to use the account id with a T-prefix. Use a bank account from [Test bank accounts](/docs/checkout/testdata/approvals/bank-accounts). For testing purposes you can also auto-approve, decline, or leave a new seller awaiting signature by adding magic values to `payout_destination_description`. See [Auto-approve sellers](/docs/checkout/testdata/approvals/auto-approve). ## Session creation Sessions can be created with the T-prefixed account as shown in [Creating Split Sessions](./creating-split-session). You can put a `payout_destination_id` created above in the split items, but any other value is also valid here. ## Payout and settlement These are not available in the sandbox environment, as it is a complicated process involving payment providers and banks. As long as the seller exists and the session is created correctly, payouts and settlements are tested to work. # Recurring subscription example Source: https://docs.dintero.com/docs/checkout/subscription-example Worked example for selling tiered yearly memberships through Dintero Checkout using stored card tokens, recurring billing, and tier upgrades or downgrades. This example details the flow for a merchant selling memberships to their club with three tiers of memberships: * **Tier 3**: Yearly 500,- * **Tier 2**: Yearly 300,- * **Tier 1**: Yearly 150,- Since these are paid in regular intervals, we will use our recurring/subscription support. Managing subscriptions for this club encompasses three different scenarios: * Creating subscription for new customer * Receive payment for subsequent periods * Upgrading the subscription from one tier to another ## Creating subscription for a new customer 1. Create a session with the subscription amount, [and specifies that a recurrence token should be created](/docs/checkout/tokenization-create-token#create-token-session) . 2. The customer [pays](/docs/checkout/display-checkout) 3. The merchant is [notified about the successful payment](/docs/checkout/after-payment#getting-notified-about-the-transaction-status). 4. The merchant [fetches and stores the token](/docs/checkout/tokenization-fetching-storing) ## Receive payment for subsequent periods 1. Create a [recurrence transaction](/docs/checkout/tokenization-use-token#recurrence-transactions) with the previously acquired token 2. The merchant will receive a synchronous response about the payment status, but should also implement a callback in case the request failed, but the payment succeeded in the background. ## Upgrading the subscription Let's say the customer has been a **tier 2** member for 6 months, but now they want to upgrade to **tier 3**. They paid 300 for the full year, and the price for **tier 3** is 500. 1. Repeat the steps from [Creating subscription for a new customer](#create-subscription) for the customer to pay 500. 2. [Refund the money] for the remaining 6 months of the **tier 2** membership, 150,- 3. The merchant stops using the old recurrence token and starts using the new for subsequent payments. [Refund the money]: /api-reference/transactions/transactions_id_refund_post # Auto-approve sellers Source: https://docs.dintero.com/docs/checkout/testdata/approvals/auto-approve Use magic values in the payout_destination_description field to auto-approve, decline, or wait for signature on a new split-payment seller in test. For testing purposes it is possible to auto-approve or decline a new seller by adding one of the following values to `payout_destination_description`: * AUTO_APPROVE Approves the case automatically, the case status will be set to `ACTIVE` * AUTO_DECLINE Declines the case automatically, the case status will be set to `DECLINED` * AUTO_WAITING_FOR_SIGNATURE Leaves the signature check for the case, the case status will be set to `WAITING_FOR_SIGNATURE` # Test bank accounts Source: https://docs.dintero.com/docs/checkout/testdata/approvals/bank-accounts Reference table of test bank account numbers for verifying seller payout destination approvals in Dintero split-payment integrations. | Country | Bank account number | Comment | | - | - | - | | NO | 86011117947 | | | NO | 0533xxxxxxx | Replace with any valid bank account number. See [Norske Testdata](https://norske-testdata.no/kontonr/) for generating a valid bank account number with a given register number | # Dintero PSP card test data Source: https://docs.dintero.com/docs/checkout/testdata/dintero-psp/checkout-dintero-cards-testdata Test card numbers, declined card scenarios, simulated authorization response codes, and 3D-Secure flows for Dintero PSP payments in the sandbox environment. Use these cards to test Dintero PSP (`dintero_psp.creditcard`) card payments in the sandbox. ### 3D-Secure All cards here will succeed all operations after performing 3DS with the exception of cards failing 3DS verification. #### Visa | Card number | Expiry | CVC | Type of test data | | - | - | - | - | | 4000 0000 0000 0002 | After the current month | Any | Skip 3DS challenge | | 4000 1000 0000 0000 | After the current month | Any | 3DS method call and challenge | | 4000 2000 0000 0008 | After the current month | Any | 3DS returns proof of attempt (ECI 6) | | 4000 3000 0000 0006 | After the current month | Any | 3DS verification fails | #### Mastercard | Card number | Expiry | CVC | Type of test data | | - | - | - | - | | 5200 0000 0000 0007 | After the current month | Any | Skip 3DS challenge | | 5200 0000 0000 0015 | After the current month | Any | 3DS method call and challenge | | 5200 0000 0000 0023 | After the current month | Any | 3DS returns proof of attempt (ECI 1) | | 5200 0000 0000 0031 | After the current month | Any | 3DS verification fails | ### Declined payments | Card number | Expiry | CVC | Type of test data | Error code | | - | - | - | - | - | | 4100 0000 0000 0076 | After the current month | Any | 3DS authentication required | `1A` | | 4100 0000 0000 0001 | After the current month | Any | Authorization timed out | Error | | 4100 0000 0000 0019 | After the current month | Any | Capture timed out | Error | | 4100 0000 0000 0027 | After the current month | Any | Refund timed out | Error | | 4100 0000 0000 0035 | After the current month | Any | Auto-capture transaction timed out | Error | | 4100 0000 0000 0043 | After the current month | Any | Cancelling transaction timed out | Error | | 4100 0000 0000 0050 | After the current month | Any | Provisioning token timed out | Error | | 5100 0000 0000 0008 | After the current month | Any | Authorization timed out | Error | | 5100 0000 0000 0016 | After the current month | Any | Capture timed out | Error | | 5100 0000 0000 0024 | After the current month | Any | Refund timed out | Error | | 5100 0000 0000 0032 | After the current month | Any | Auto-capture transaction timed out | Error | | 5100 0000 0000 0040 | After the current month | Any | Cancelling transaction timed out | Error | | 5100 0000 0000 0057 | After the current month | Any | Provisioning token timed out | Error | ### Simulate response codes A specific response from Visa or Mastercard can be simulated in test mode by setting the transaction amount to `995XX` in major units, where `XX` is the two-digit response code. Minor units are currently ignored. For example, an amount of `99501.00` will result in a response code of `01`, see the table below. | Amount | Response code | | - | - | | 99501.00 | `01` | | 99501.99 | `01` | | 99519.00 | `19` | If the resulting response code indicates success for the given card brand, the transaction will succeed, otherwise it will fail. For failed transactions a list of error codes and a retry policy will be returned. The error codes will generally only contain one entry, but if a new error code is introduced you might receive both the old and new codes. The retry policy will contain an array of retry codes in the same manner as the error codes. If the retry policy indicates that you should retry after a delay, we will also include an ISO 8601 timestamp after which you can retry the operation. #### Visa amounts | Amount | Error code | Retry policy | Reason | | - | - | - | - | | 99500.00 | N/A | N/A | Approved and completed successfully | | 99501.00 | `ISSUER_ERROR` | `RETRY_AFTER_DELAY` | Refer to issuer | | 99502.00 | `ISSUER_ERROR` | `RETRY_AFTER_DELAY` | Refer to issuer | | 99503.00 | `INVALID_MERCHANT` | `RETRY_AFTER_DELAY` | Invalid merchant | | 99504.00 | `PICK_UP_CARD` | `DO_NOT_RETRY` | Pick up card (no fraud suspected) | | 99505.00 | `DECLINED` | `RETRY_AFTER_DELAY` | Do not honor | | 99506.00 | `ERROR` | `RETRY_AFTER_DELAY` | Error | | 99507.00 | `PICK_UP_CARD` | `DO_NOT_RETRY` | Pick up card (fraud account) | | 99510.00 | N/A | N/A | Partial approval | | 99511.00 | N/A | N/A | Approved VIP | | 99512.00 | `INVALID_TRANSACTION` | `DO_NOT_RETRY` | Invalid transaction | | 99513.00 | `INVALID_AMOUNT` | `RETRY_AFTER_DELAY` | Invalid amount or currency conversion field overflow | | 99515.00 | `ISSUER_ERROR` | `DO_NOT_RETRY` | No such issuer | | 99519.00 | `DECLINED` | `RETRY_AFTER_DELAY` | Re-enter transaction | | 99521.00 | `DECLINED` | `RETRY_AFTER_DELAY` | No action taken | | 99525.00 | `ERROR` | `RETRY_AFTER_DELAY` | Unable to locate record in file | | 99528.00 | `ISSUER_ERROR` | `RETRY_AFTER_DELAY` | File temporarily not available for update or inquiry | | 99539.00 | `DECLINED` | `RETRY_AFTER_DELAY` | No credit account | | 99541.00 | `PICK_UP_CARD` | `DO_NOT_RETRY` | Lost card | | 99543.00 | `PICK_UP_CARD` | `DO_NOT_RETRY` | Stolen card | | 99546.00 | `CLOSED_ACCOUNT` | `DO_NOT_RETRY` | Deactivated token | | 99551.00 | `INSUFFICIENT_FUNDS` | `RETRY_AFTER_DELAY` | Insufficient funds | | 99552.00 | `DECLINED` | `RETRY_AFTER_DELAY` | No checking account | | 99554.00 | `EXPIRED_CARD` | `RETRY_AFTER_DELAY` | Expired card or expiration date is missing | | 99555.00 | `FAILED_VERIFICATION` | `RETRY_AFTER_DELAY` | Failed verification | | 99557.00 | `TRANSACTION_NOT_PERMITTED` | `DO_NOT_RETRY` | Transaction not permitted to cardholder | | 99559.00 | `DECLINED` | `RETRY_AFTER_DELAY` | Suspected fraud | | 99561.00 | `EXCEEDS_APPROVAL_LIMIT` | `RETRY_AFTER_DELAY` | Exceeds approval amount limit | | 99562.00 | `RESTRICTED_CARD` | `RETRY_AFTER_DELAY` | Restricted card (card invalid in this region or country) | | 99563.00 | `ERROR` | `RETRY_AFTER_DELAY` | Security violation | | 99564.00 | `DECLINED` | `RETRY_AFTER_DELAY` | Transaction does not fulfill anti-money laundering requirement | | 99565.00 | `EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT` | `RETRY_AFTER_DELAY` | Exceeds withdrawal frequency limit | | 99578.00 | `ISSUER_ERROR` | `RETRY_AFTER_DELAY` | Blocked, first used. Transaction from new cardholder, and card not properly unblocked | | 99585.00 | N/A | N/A | Not declined, valid transaction | | 401.00 | `ADDITIONAL_VERIFICATION_REQUIRED` | `RETRY_IMMEDIATELY` | Additional customer authentication required | | 88.51 | N/A | N/A | Approved, but authorization expires after 1 minute | #### Mastercard amounts > **Note:** The retry policy shown here reflects the simulator's behavior, which always falls back to the default retry policy. In production, Mastercard's > retry policy is derived from the merchant advice code (MAC) returned by the issuer in the network response, and may therefore differ from the values below > (e.g. `DO_NOT_RETRY`, or `RETRY_AFTER_DELAY` with a different delay such as 1 hour, 2/4/6/8/10 days). | Amount | Error codes | Retry policy | Reason | | - | - | - | - | | 99500.00 | N/A | N/A | Approved and completed successfully | | 99501.00 | `ISSUER_ERROR` | `RETRY_AFTER_DELAY` | Refer to card issuer | | 99503.00 | `INVALID_MERCHANT` | `RETRY_AFTER_DELAY` | Invalid merchant | | 99504.00 | `PICK_UP_CARD` | `DO_NOT_RETRY` | Pick Up Card (No Fraud) | | 99505.00 | `DECLINED` | `RETRY_AFTER_DELAY` | Do Not Honor | | 99508.00 | N/A | N/A | Honor with ID | | 99510.00 | N/A | N/A | Partial approval | | 99512.00 | `INVALID_TRANSACTION` | `RETRY_AFTER_DELAY` | Invalid transaction | | 99513.00 | `INVALID_AMOUNT` | `RETRY_AFTER_DELAY` | Invalid amount | | 99514.00 | `ERROR` | `RETRY_AFTER_DELAY` | Error | | 99515.00 | `ISSUER_ERROR` | `RETRY_AFTER_DELAY` | No such issuer | | 99530.00 | `INVALID_TRANSACTION` | `RETRY_AFTER_DELAY` | Format error | | 99541.00 | `PICK_UP_CARD` | `DO_NOT_RETRY` | Lost Card | | 99543.00 | `PICK_UP_CARD` | `DO_NOT_RETRY` | Stolen Card | | 99546.00 | `CLOSED_ACCOUNT` | `DO_NOT_RETRY` | Closed Account | | 99551.00 | `INSUFFICIENT_FUNDS` | `RETRY_AFTER_DELAY` | Insufficient Funds/Over credit limit | | 99554.00 | `EXPIRED_CARD` | `RETRY_AFTER_DELAY` | Expired Card | | 99555.00 | `FAILED_VERIFICATION` | `RETRY_AFTER_DELAY` | Failed verification | | 99557.00 | `TRANSACTION_NOT_PERMITTED` | `RETRY_AFTER_DELAY` | Transaction not permitted to issuer/cardholder | | 99561.00 | `EXCEEDS_APPROVAL_LIMIT` | `RETRY_AFTER_DELAY` | Exceeds withdrawal amount limit | | 99562.00 | `RESTRICTED_CARD` | `DO_NOT_RETRY` | Restricted Card | | 99563.00 | `ERROR` | `RETRY_AFTER_DELAY` | Security violation | | 99565.00 | `ADDITIONAL_VERIFICATION_REQUIRED` | `RETRY_AFTER_DELAY` | Additional customer authentication required | | 99570.00 | `ISSUER_ERROR` | `RETRY_AFTER_DELAY` | Contact card issuer | | 99572.00 | `ISSUER_ERROR` | `RETRY_AFTER_DELAY` | Account not yet activated | | 99583.00 | `DECLINED` | `RETRY_AFTER_DELAY` | Suspected fraud | | 99585.00 | N/A | N/A | Not declined, valid transaction | | 99587.00 | N/A | N/A | No cash back allowed | | 401.00 | `ADDITIONAL_VERIFICATION_REQUIRED` | `RETRY_IMMEDIATELY` | Additional customer authentication required | | 88.51 | N/A | N/A | Approved, but authorization expires after 1 minute | ### Error codes and retry policy #### Error codes | Error codes | Description | | - | - | | `ERROR` | An error has happened. You can see the error message/reason for more context | | `DECLINED` | The operation was declined. You can see the error message/reason for more context | | `ISSUER_ERROR` | An error related to the issuer. Usually cardholder needs to contact issuer | | `PICK_UP_CARD` | Mostly relevant for in-person payments, indicating the card should not be returned (e.g. lost or stolen card) | | `INVALID_MERCHANT` | Merchant is not allowed to process the transaction (e.g. invalid MCC, merchant is not permitted to process the transaction, regulatory restrictions) | | `INVALID_TRANSACTION` | Transaction was declined because it's not permitted for the cardholder or card | | `INVALID_AMOUNT` | Amount provided is invalid | | `INSUFFICIENT_FUNDS` | Not enough funds on card to fulfill transaction | | `CLOSED_ACCOUNT` | The account has been closed | | `EXPIRED_CARD` | Card is expired or the expiration date is invalid or missing | | `TRANSACTION_NOT_PERMITTED` | The transaction is not permitted to the cardholder or the card type | | `EXCEEDS_APPROVAL_LIMIT` | Declined because the amount limits for the card/account has been exceeded, or because issuer/acquirer risk cap has been exceeded | | `EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT` | Declined because the maximum allowed withdrawals has been reached | | `RESTRICTED_CARD` | The card is restricted from performing the transactions, usually related to region locks | | `FAILED_VERIFICATION` | The card has failed some verification (e.g. PIN verification, CVV) | | `ADDITIONAL_VERIFICATION_REQUIRED` | Soft decline, the issuer has requested additional verification. Will generally be handled by performing 3DS | | `AUTHORIZATION_EXPIRED` | Operation failed due to authorization having expired | #### Retry codes | Retry code | Description | | - | - | | `DO_NOT_RETRY` | The transactions should not be retried | | `RETRY_IMMEDIATELY` | You can retry the transaction immediately. If it fails again you should not retry again | | `RETRY_AFTER_DELAY` | You can retry again after a delay. You should also receive a timestamp that indicates when you can retry again | # Worldline (Bambora) test data Source: https://docs.dintero.com/docs/checkout/testdata/other/checkout-bambora-testdata Test Visa and Mastercard card numbers for verifying Worldline (Bambora) card payments in the Dintero Checkout sandbox. Use these cards to test Worldline (`bambora.creditcard`) card payments in the sandbox. | Card type | Card number | Expiry | CVC | | - | - | - | - | | Visa | 4154210000000001 | After the current month | Any | | Mastercard | 5156230000000004 | After the current month | Any | # Billie test data Source: https://docs.dintero.com/docs/checkout/testdata/other/checkout-billie-testdata Test company data for verifying Billie B2B payments in Sweden in the Dintero Checkout sandbox. ## Sweden B2B customers (businesses) | Company name. | Organization. no | Address | Zip code | City | First Name | Last Name | Phone | Email | | - | - | - | - | - | - | - | - | - | | Arvidsjaurs Målare AB | `556779-5553` | Box 6865 | 86025 | Sundsvall | Test | Person | `+46765260000` | `Test-se@billie.io` | # Discount code test data Source: https://docs.dintero.com/docs/checkout/testdata/other/checkout-discount-codes-testdata Test discount codes for verifying discount flows in the Dintero Checkout sandbox. | Discount code | Discount | | - | - | | save20 | 20% | | CODE1 | 50% | | CODE2 | 50% | # Gift card test data Source: https://docs.dintero.com/docs/checkout/testdata/other/checkout-giftcards-testdata Test gift card numbers and PINs for verifying gift card payments in the Dintero Checkout sandbox. | Gift card number | PIN | Amount | | - | - | - | | 0320988885 | 7091 | 100 NOK | | 2726208402 | 6521 | 1000 NOK | # In-person payment test data Source: https://docs.dintero.com/docs/checkout/testdata/other/checkout-in-person-testdata Test in-person (terminal) payments in the Dintero sandbox using the Visa CDET and American Express Payment Test Emulator Android apps to simulate contactless cards. To test an in-person payment you need a Dintero payment terminal in the sandbox and something to tap against it. Instead of a stack of physical test cards, use a card emulator app on an Android phone. The app turns your phone into a contactless test card: * **Visa**: [Visa CDET](https://play.google.com/store/apps/details?id=com.visa.app.cdet) (Contactless Device Evaluation Toolkit), with several card profiles and edge cases. * **American Express**: [American Express Payment Test Emulator](https://play.google.com/store/apps/details?id=com.americanexpress.android.testemulator). > [!TIP] > > To test without a physical terminal, use a [simulated terminal](/docs/checkout/in-person/simulated-terminals). > [!NOTE] > > The emulator apps are intended for testing only. Use them against terminals that are configured for the sandbox environment, never against production terminals. ## What you need * An Android device with NFC. * A Dintero payment terminal registered to a store in the sandbox. See [terminal onboarding](/docs/checkout/in-person/terminal-onboarding). * The ability to change the phone's default wallet / contactless payment app. ## Visa ### Install the Visa CDET app Install **Visa CDET Application** from the Google Play Store: > [card] [Visa CDET on Google Play](https://play.google.com/store/apps/details?id=com.visa.app.cdet) > > `com.visa.app.cdet` ### Set CDET as the default wallet app For the terminal to talk to CDET instead of Google Wallet (or any other wallet), you need to make CDET the default contactless payment app on the phone. **1. Open the NFC / wallet settings** On your Android device, open **Settings** and search for *Default wallet app* (sometimes under **Connected devices** > **NFC** > **Contactless payments**). The exact path varies by manufacturer. **2. Select CDET** Choose **CDET** from the list of installed wallet apps. ![Selecting CDET as the default wallet app in Android settings](https://mintcdn.com/dintero-c3a7bfec/lok_9fdq3SgYG0jo/docs/checkout/testdata/other/assets/cdet-default-wallet-app.jpg?fit=max\&auto=format\&n=lok_9fdq3SgYG0jo\&q=85\&s=9ab8a7d70607bb95813409ab3ee49a83) > [!WARNING] > > Switch the default back to your normal wallet app when you're done testing. Otherwise real contactless payments from the phone will stop working. ### Test cards Open the **Visa CDET Application**. You'll see a list of test cards, each modeling a specific card profile or edge case (baseline Visa Contactless Payment Specification (VCPS) compliance, unusual Processing Options Data Object List (PDOL) requests, multi-application cards, missing cardholder name, and so on). ![List of CDET test cards with different behaviors](https://mintcdn.com/dintero-c3a7bfec/lok_9fdq3SgYG0jo/docs/checkout/testdata/other/assets/cdet-card-list.jpg?fit=max\&auto=format\&n=lok_9fdq3SgYG0jo\&q=85\&s=9f06c683b567352fdcc958a91f088477) Select the card that matches the scenario you want to test, then tap the phone against the terminal when it prompts for payment. | Card | Typical use | | - | - | | **Card 01**: CDET Baseline (VCPS 2.0.2) | Happy-path contactless payment. | | **Card 02**: CDET Baseline (VCPS 2.2) | Happy-path contactless payment on a newer VCPS version. | | **Card 03**: 16-byte ADF, 2-byte TTQ, min-length cardholder name | Exercise the terminal's handling of unusual Application Definition File (ADF), Terminal Transaction Qualifiers (TTQ), PDOL, and cardholder name values. | | **Card 04**: Multi-application card, no cardholder name | Verify behavior when the card exposes additional applications and omits the cardholder name. | Refer to the card description shown in the app for the exact behavior of each entry. The list is maintained by Visa and updated with each CDET release. ## American Express > [!NOTE] > > American Express on terminals is only available to merchants with a direct agreement with American Express. ### Install the American Express emulator Install **American Express Payment Test Emulator** from the Google Play Store: > [card] [American Express Payment Test Emulator on Google Play](https://play.google.com/store/apps/details?id=com.americanexpress.android.testemulator) > > `com.americanexpress.android.testemulator` ### Test cards **1. Open contactless mode** Open the **American Express Payment Test Emulator** and tap **Contactless**. **2. Choose a test card** Select the card you want to test with. **3. Tap the phone against the terminal** Tap the phone against the terminal when it prompts for payment. ## Run a sandbox payment **1. Create a terminal session** Create a session that targets your sandbox terminal. See [creating a terminal session](/docs/checkout/in-person/creating-terminal-session). **2. Tap the phone against the terminal** When the terminal prompts for payment, hold the phone against the terminal's contactless zone. Select the desired test card first. **3. Observe the result** The terminal completes the flow as if a real card were tapped. The resulting transaction shows up in Backoffice and via the standard Checkout API, so you can verify authorization, capture, and callback handling end-to-end. ## Related > [card] [Onboard a terminal](/docs/checkout/in-person/terminal-onboarding) > > Register a store and link a terminal before you start testing. > [card] [Create a terminal session](/docs/checkout/in-person/creating-terminal-session) > > Build the session payload that drives the terminal. # Instabank test data Source: https://docs.dintero.com/docs/checkout/testdata/other/checkout-instabank-testdata Test SSNs and BankID credentials for verifying Instabank Finance payments in the Dintero Checkout sandbox. ## Instabank Finance | Status | SSN | BankID OTP | BankID Password | | - | - | - | - | | Approved | 01087409968 | otp | qwer1234 | | Rejected | 2001791617 | otp | qwer1234 | # Klarna test data Source: https://docs.dintero.com/docs/checkout/testdata/other/checkout-klarna-testdata Test data for Klarna B2C and B2B flows in Norway, including approved, denied, and dispute scenarios in the Dintero Checkout sandbox. ## Norway B2C customers (individuals) | Flow | Email address | Phone number | | - | - | - | | Approved | `customer@email.no` | `+4740123456` | | Denied | `customer+denied@email.no` | `+4740123457` | | Dispute: return | `customer+disputed-return@email.no` | `+4740123474` | | Dispute: goods not received | `customer+disputed-goods_not_received@email.no` | `+4740123475` | | Dispute: order already paid | `customer+disputed-already_paid@email.no` | `+4740123476` | | Dispute: faulty goods | `customer+disputed-faulty_goods@email.no` | `+4740123477` | | Dispute: incorrect invoice | `customer+disputed-incorrect_invoice@email.no` | `+4740123478` | | Dispute: high-risk order | `customer+disputed-high_risk_order@email.no` | `+4740123479` | | Dispute: unauthorized purchase | `customer+disputed-unauthorized_purchase@email.no` | `+4740123480` | Test data for fields in the Klarna form: | Field | Approved | Denied | Other flows | | - | - | - | - | | First name | Jane | Test | Person NO | | Last name | Test | Person-no | Test | | Address | Edvards Munchs Plass 1 | Sæffleberggate 56 | Edvards Munchs Plass 1 | | Zip code | 0194 | 0563 | 0194 | | City | Oslo | Oslo | Oslo | | Country | NO | NO | NO | | Date of birth (DD-MM-YYYY) | 01-08-1970 | 01-08-1970 | 01-01-2000 | | Personal number | `NO01087000571` | `NO01087000148` |
  • Dispute: return
  • `NO30062449205`
  • Dispute: goods not received
  • `NO27083206670`
  • Dispute: order already paid
  • `NO14040845144`
  • Dispute: faulty goods
  • `NO16089639496`
  • Dispute: incorrect invoice
  • `NO19046731789`
  • Dispute: high-risk order
  • `NO27115906319`
  • Dispute: unauthorized purchase
  • `NO25064127953`
| | OTP (Random 6 digits different from 999999) | 123456 | 123456 | 123456 | ## Norway B2B customers (businesses) | Field | Approved | Denied | | - | - | - | | Company registration number | 999999999 | 811111112 | | Company name | Testcompany-no | Testcompany-no | | Street | Sæffleberggate 56 | Sæffleberggate 56 | | Zip code | 0563 | 0563 | | City | Oslo | Oslo | | Email | `youremail@email.com` | `youremail+denied@email.com` | Further test data for Klarna can be found in [Klarna's sample customer data](https://docs.klarna.com/resources/developer-tools/sample-data/sample-customer-data/#europe-norway). # Kravia test data Source: https://docs.dintero.com/docs/checkout/testdata/other/checkout-kravia-testdata Test email aliases for verifying Kravia invoice payment outcomes in the Dintero Checkout sandbox. Use the following email aliases to test Kravia invoice payment outcomes. ## Individual invoices Individual invoices are fully paid by default. Use `+unpaid` to prevent simulated payment, or choose an alias below to test partial or multiple payments. | Scenario | Email address | Result | | - | - | - | | Fully paid (default) | `customer@example.com` | 100% payment | | Unpaid | `customer+unpaid@example.com` | No simulated payment | | Partially paid | `customer+partial@example.com` | 50% payment | | Fully paid with multiple payments | `customer+multiple-paid@example.com` | 50%, 30%, 20% payments | | Partially paid with multiple payments | `customer+multiple-partial@example.com` | 30%, 30% payments | The `+unpaid` alias takes precedence if combined with a payment alias. Without a recognized alias, the simulator uses the default full payment. ## Grouped invoices To test `kravia.invoice_b2b_grouped`: 1. Create one or more purchases for the same customer, with the same billing details and within the same billing period, using `customer@example.com`. 2. On the final purchase for that customer, use `customer+group-end@example.com` to close the group and simulate payment. This combines the purchases into one invoice and simulates full payment. Add `+partial`, `+multiple-paid`, or `+multiple-partial` to test the other outcomes above. For example, `customer+group-end+partial@example.com` pays 50% of the combined invoice. Without `+group-end`, the group remains unpaid by the simulator. See [Grouped invoices](/docs/checkout/kravia/grouped-invoices) for customer grouping rules. > [!NOTE] > > The email addresses above are examples. Use any email address and add the relevant `+tag` before `@`. # MobilePay test data Source: https://docs.dintero.com/docs/checkout/testdata/other/checkout-mobilepay-testdata Test phone number for verifying MobilePay DKK purchases in the Dintero Checkout sandbox. For testing a positive *DKK* purchase, use any Danish mobile number. For example: `+45 22222222`. # Swedbank test data Source: https://docs.dintero.com/docs/checkout/testdata/other/checkout-swedbank-testdata Test Visa, Mastercard, and Amex card numbers, tokens, and magic amounts for verifying Swedbank Pay integrations in Dintero Checkout sandbox. ## Swedbank Use these cards to test Swedbank (`payex.creditcard`) card payments in the sandbox. ### Visa | Card number | Expiry | CVC | Type of test data | | - | - | - | - | | 4925000000000004 | After the current month | Any | Loopback only | | 4581097032723517 | After the current month | Any | Loopback only | | 4581099940323133 | After the current month | Any | Loopback only | | 4581096604172848 | After the current month | Any | Loopback only | | 4761739001010416 | After the current month | Any | 3DS enrolled, ECI 5, Evry & loopback | | 4581096477726290 | After the current month | 019 | Swedbank & loopback | ### MasterCard | Card number | Expiry | CVC | Type of test data | | - | - | - | - | | 5226612199533406 | 09/28 | 602 | 3DS enrolled, ECI 6, Evry & loopback | | 5413066399580167 | After the current month | Any | Loopback only | | 5226609999109486 | After the current month | Any | Loopback only | | 5226600159865967 | After the current month | Any | Loopback only | | 5226603115488031 | After the current month | Any | Loopback only | | 5226604266737382 | After the current month | Any | Loopback only | | 5226600156995650 | After the current month | Any | Loopback only | ### Example tokens | Card number | Token | CVC | | - | - | - | | 4925000000000004 | 1333e495-6ac0-4722-9aa2-5fefd339a40f | Any | | 5413066399580167 | d18c7744-9838-4f05-9931-1b3ffedaeea1 | Any | ### Swedbank creditcard - magic amounts (error testing using amounts) | Amount | Error Code | Description | | - | - | - | | 900305 | MONTHLYLIMITEXCEEDED | The monthly attempt limit has been exceeded | | 900313 | REJECTED_BY_ACQUIRER_INVALID_AMOUNT | Invalid amount, response-code: 13 | | 900330 | REJECTED_BY_ACQUIRER_FORMAT_ERROR | Format error, response-code: 30 | | 900334 | REJECTED_BY_ACQUIRER_POSSIBLE_FRAUD | Possible fraud, response-code: 34 | | 900343 | REJECTED_BY_ACQUIRER_CARD_STOLEN | Card stolen, response-code: 43 | | 900354 | REJECTED_BY_ACQUIRER_CARD_EXPIRED | Card expired, response-code: 54 | | 900351 | REJECTED_BY_ACQUIRER | Unknown error, response-code: 51 | | 900359 | REJECTED_BY_ACQUIRER_POSSIBLE_FRAUD | Possible fraud, response-code: 59 | | 900361 | REJECTED_BY_ACQUIRER_INSUFFICIENT_FUNDS | Insufficient funds, response-code: 61 | | 900362 | REJECTED_BY_ACQUIRER | Unknown error, response-code: 62 | | 900391 | ACQUIRER_HOST_OFFLINE | Acquirer host offline, response-code: 91 | | 952400 | DONOTRETRY | Transaction declined, do not retry | | 952501 | MODIFICATIONSREQUIRED | Transaction is declined and needs modifications | | 952100 | DAILYLIMITEXCEEDED | The daily attempt limit has been exceeded | > The `DAILYLIMITEXCEEDED` must be performed 10 times to be triggered, and the > `MONTHLYLIMITEXCEEDED` has to be performed 15 times to be triggered. > The `SuspensionWarning` response message appears when the two limit exceeds > have 5 attempts left (i.e. after 5 daily or 10 monthly attempts). # Swish test data Source: https://docs.dintero.com/docs/checkout/testdata/other/checkout-swish-testdata Test phone number for verifying Swish SEK purchases in the Dintero Checkout sandbox. For testing a positive *SEK* purchase, use any Swedish mobile number. For example: `+46 739000001`. # Two test data Source: https://docs.dintero.com/docs/checkout/testdata/other/checkout-two-testdata Test companies, credit limits, and order verification thresholds for verifying Two B2B payments in Norway and Sweden in the Dintero Checkout sandbox. ## Norway Default credit limit: Kr 1,000,000.00. Credit availability is affected by sandbox test orders; cancel unfulfilled or refund fulfilled orders to restore it. **Order verification thresholds:** | Amount | Verification | | - | - | | \< Kr 5,000 | Skip | | Kr 5,000 – 9,999 | Email code | | Kr 10,000 – 49,999 | Vipps Verification + Legal Rep | | >= Kr 50,000 | Vipps Verification + Legal Rep (Legal Rep also required) | Default onboarding: Email code verification. Vipps Verification + Legal Rep onboarding is always approved. | Company | Org. no | Credit limit | Notes | | - | - | - | - | | INOKIM NORWAY AS | 922934479 | Kr 1,000,000 | Exempt from credit calc; onboarding: Vipps + Legal Rep | | STRISE AS | 918330100 | Kr 1,000,000 | Exempt; onboarding: Skip | | FURE MEKANISKE AS | 985094918 | Kr 1,000,000 | Exempt; onboarding: Skip | | DATAGRUPPEN AS | 923668853 | Kr 1,000,000 | Exempt; onboarding: Vipps + Legal Rep; verification: Accept | | SCANDINAVIAN CAR STYLING AB | 919168633 | Kr 500,000 | Onboarding: Vipps + Legal Rep; verification: Accept | | MOBIT NORGE AS | 974397986 | Kr 250,000 | Verification: Accept | | MEDIAHUSET NAUST MEDIA | 983772102 | Kr 100,000 | Fraud rejected | | BIRGER N HAUG AS | 952335863 | Kr 10,000 | Blocked in arrears | | AI VISIONS AS | 997802020 | Kr 2,000 | | | THE GOOD GUYS AS | 922422508 | Kr 0 | Zero credit; fails order intent | | ALFA OPPUSSING AS | 925718955 | Kr 1,000,000 | Blocked in arrears | | STOPPEFFEKT AS | 920245404 | Kr 1,000,000 | Verification: Decline | | SAMEIET AASGARDEN 930 | 920069800 | Kr 1,000,000 | Verification: Decline; fraud rejected | ## Sweden Default credit limit: Kr 1,000,000.00. Credit availability is affected by sandbox test orders; cancel unfulfilled or refund fulfilled orders to restore it. **Order verification thresholds:** | Amount | Verification | | - | - | | \< Kr 5,000 | Skip | | Kr 5,000 – 9,999 | Email | | Kr 10,000 – 49,999 | BankID + Legal Rep | | >= Kr 50,000 | BankID + Legal Rep (Legal Rep also required) | Default onboarding: Email code verification. BankID + Legal Rep onboarding is always approved. | Company | Org. no | Credit limit | Notes | | - | - | - | - | | LIDINGO KOMMUN | 212000-0191 | Kr 1,000,000 | Exempt; onboarding: BankID + Legal Rep; verification: Accept | | VOLUMENTAL AB | 556912-4141 | Kr 1,000,000 | Exempt; onboarding: BankID | | FISHBRAIN AB (PUBL) | 556796-5370 | Kr 1,000,000 | Exempt | | BETTER AUTOMATION SWEDEN AB | 559418-2528 | Kr 1,000,000 | Exempt; onboarding: BankID + Legal Rep; verification: Accept | | IT MARKET SWEDEN AB | 556709-2324 | Kr 1,000,000 | Exempt; onboarding: BankID + Legal Rep; verification: Accept | | ARJEPLOGS KOMMUN | 212000-2668 | Kr 500,000 | Onboarding: Skip; verification: Accept | | MAKRO KONSULT AKTIEBOLAG | 556039-1954 | Kr 250,000 | Onboarding: Skip; verification: Accept | | GEGA AB | 556781-2903 | Kr 100,000 | | | STRONG FOOLS STRONGMAN | 802546-5751 | Kr 10,000 | | | TET VIET | 802544-0556 | Kr 2,000 | | | Bad Brothers Band AB | 802536-7528 | Kr 0 | Zero credit; fails order intent | | Bada Bing Bada Boom AB | 559256-8892 | Kr 0 | Zero credit; fails order intent | | TERMINO C 9330 AB | 556676-1986 | Kr 1,000,000 | Blocked in arrears | | BADAREN HB | 969667-9449 | Kr 1,000,000 | Blocked in arrears | | SLUTA NU | 802515-6228 | Kr 1,000,000 | Verification: Decline | | DADAI AB | 559507-7347 | Kr 1,000,000 | Verification: Decline | | PRECIS AKTIEBOLAG | 556254-3321 | Kr 1,000,000 | Fraud rejected | | TERMINO C 11111 AB | 559405-3661 | Kr 1,000,000 | Fraud rejected | # Vipps test data Source: https://docs.dintero.com/docs/checkout/testdata/other/checkout-vipps-testdata Test civic registration number and phone number for verifying Vipps payments in the Dintero Checkout sandbox. | Civ. reg. no | Phone number | Phone number verification | | - | - | - | | 12102407944 | +47 40230256 | Any number | See instructions for installing the [Vipps test app](https://developer.vippsmobilepay.com/docs/knowledge-base/test-environment#test-apps), which is required to authorize a Vipps payment. # Walley test data Source: https://docs.dintero.com/docs/checkout/testdata/other/checkout-walley-testdata Test persons and businesses for verifying Walley payments in Norway, Sweden, Denmark, and Finland in the Dintero Checkout sandbox. ## Norway Any civic reg. no. can be used for testing purposes, as long as it is in a standard format, and the test person is above 18 years of age. For BankID Norway, see Signicat's [Norwegian BankID test information](https://developer.signicat.com/enterprise/identity-methods/norwegian-bankid.html#test-information). ### B2C customers (consumers) | Status | First name | Last name | Address | Zip code | City | Civ. reg. no | Email | Phone number | | - | - | - | - | - | - | - | - | - | | Approved | Approved23 | Norway23 | STORGATA 1 | 9300 | FINNSNES | 01028049923 | Your own | Your own | | Approved | Approved42 | Norway42 | STORGATA 15 | 9300 | FINNSNES | 01028049842 | Your own | Your own | | Rejected | Rejected49 | Norway49 | RADARVEIEN 22 | 1152 | OSLO | 01019949849 | Your own | Your own | The above is the official test data. When using these users it's important to use the name, address and reg. no. provided. You can also use other names, and a valid Norwegian social security number, for example: | Status | First name | Last name | Address | Zip code | City | Civ. reg. no | Email | Phone number | | - | - | - | - | - | - | - | - | - | | Approved | Demo | Person | Gaustadalleen 21 | 0349 | Oslo | 14127638757 | Your own | Your own | ### B2B customers (businesses) | Status | Company name. | Address | Zip code | City | Organization. no | | - | - | - | - | - | - | | Approved | Svar Direkte As | C/O Testgruppen | 0508 | Oslo | 937340303 | | Not approved | Not Approved AS | Testgatan 1 | 0508 | Oslo | 927822334 | ## Sweden ### B2C customers (consumers) **Approved test persons:** Any civic reg. no. can be used for testing purposes, as long as it is in a standard format, and the test person is above 18 years of age. You can use [personnummer.nu](https://www.personnummer.nu) to create a valid personnummer for Sweden. **Rejected test persons:** | Status | First name | Last name | Address | Zip code | City | Civ. reg. no | Email | Phone number | | - | - | - | - | - | - | - | - | - | | Not approved | Rejected00 | Sweden00 | STORGATAN 2 | 84093 | HEDE | 9901010000 | Your own | Your own | | Not approved | Rejected18 | Sweden18 | STORGATAN 3 | 84093 | HEDE | 9901010018 | Your own | Your own | For BankID Sweden, see Signicat's [Swedish BankID test information](https://developer.signicat.com/enterprise/identity-methods/swedish-bankid.html#test-information). ## Denmark See [Walley's Denmark test persons documentation](https://dev.walleypay.com/docs/paymentsApi/testpersons/denmark). ## Finland See [Walley's Finland test persons documentation](https://dev.walleypay.com/docs/paymentsApi/testpersons/finland). ## Testing ON_HOLD When using the email address `onhold@collectorbank.se`, purchases will be put on hold. Use this email address with your choice of phone number and one of the social security numbers above. The payment will be put in status `ON_HOLD` in Dintero's system. To complete or decline the payment, a GET request to the Collector anti-fraud callback endpoint is needed. Contact Dintero if you need to test this. # Card tokenization overview Source: https://docs.dintero.com/docs/checkout/tokenization Tokenize customer cards through Dintero so you can store them safely and charge them later for subscriptions, recurring billing, or one-click checkout. To save a customer's card info, you can tokenize the card and store it for future use. ## Prerequisites > [!WARNING] > > **Tokenization must be activated on your account before you can create or charge card tokens.** > > Contact your Dintero account manager to have it enabled. Until it is activated, requests > that create or use a card token will fail. ## Supported providers The examples in this section use `payex.creditcard`, `bambora.creditcard`, and `dintero_psp.creditcard`. For the full list of payment product types that support tokenization, and the token types each one issues, see the [`token_provider` schema](/api-reference/session/checkout_payment_token_session_post#body-token-provider). ## Token types Swedbank Pay uses two types of tokens: * **payment_token** * **recurrence_token** While Bambora (Worldline) and Dintero PSP use the payment token for all use cases: * **payment_token** ### Payment token A payment token can be used to create payment where the card details will be prefilled in the checkout. The payer still has to enter the `CVC` to complete the purchase. The payment token can also be used to perform unscheduled purchase without involving the payer, also known as an merchant initiated transaction (MIT) For payment providers that don't support recurrence tokens, payment tokens can be used to create recurring payments. ### Recurrence token A recurrence token can be used to create recurring payment where you can charge a card without payer interaction. When an initial payment token is generated, subsequent payments are made through server-to-server request ## What's next > [card] [Create a token](/docs/checkout/tokenization-create-token) > > Create a token in advance with a zero-amount setup, or during a regular purchase. > [card] [Fetch and store tokens](/docs/checkout/tokenization-fetching-storing) > > Retrieve the token from the transaction and persist it securely. > [card] [Use a stored token](/docs/checkout/tokenization-use-token) > > Charge a stored card for customer initiated and merchant initiated payments. > [card] [Error handling](/docs/checkout/tokenization-error-handling) > > Retry limits, blocked cards, and how to avoid duplicate transactions. # Create a card token Source: https://docs.dintero.com/docs/checkout/tokenization-create-token Create a Dintero card token either in advance with a zero-amount setup or during a regular purchase, ready to be reused for later customer or merchant payments. > [!WARNING] > > **Tokenization must be activated on your account before you can create or charge card tokens.** > > Contact your Dintero account manager to have it enabled. Until it is activated, requests > that create or use a card token will fail. There are two ways of creating a card token, either in advance, without withdrawing any money, or during a purchase process. ### Creating token in advance To store a token without performing a payment, do the following: #### Authentication To authenticate, you create a [Checkout API client] and use the credentials to [Create an access token]. The same client can be used for Sandbox mode and production. For all requests to the API set the following header: ```http theme={null} Authorization: Bearer {access_token} ``` [Checkout API client]: /docs/checkout/checkout-client [Create an access token]: /docs/checkout/checkout-client#authentication #### Create token session With the access token, call [Payment token session][payment token session] with this body: > [tab] payex.creditcard > > ```json theme={null} > { > "session": { > "order": { > "currency": "NOK", > "merchant_reference": "order-number" > }, > "url": { > "return_url": "https://example.com/accept", > "callback_url": "https://example.com/callback?method=GET", > "merchant_terms_url": "https://example.com/terms.html" > }, > "customer": { > "email": "john.doe@example.com", > "phone_number": "+4799999999" > } > }, > "token_provider": { > "payment_product_type": "payex.creditcard", > "token_types": ["payment_token", "recurrence_token"] > } > } > ``` > [tab] bambora.creditcard > > ```json theme={null} > { > "session": { > "order": { > "currency": "NOK", > "merchant_reference": "order-number" > }, > "url": { > "return_url": "https://example.com/accept", > "callback_url": "https://example.com/callback?method=GET", > "merchant_terms_url": "https://example.com/terms.html" > }, > "customer": { > "email": "john.doe@example.com", > "phone_number": "+4799999999" > } > }, > "token_provider": { > "payment_product_type": "bambora.creditcard", > "token_types": ["payment_token"] > } > } > ``` > [tab] dintero_psp.creditcard > > ```json theme={null} > { > "session": { > "order": { > "currency": "NOK", > "merchant_reference": "order-number" > }, > "url": { > "return_url": "https://example.com/accept", > "callback_url": "https://example.com/callback?method=GET", > "merchant_terms_url": "https://example.com/terms.html" > }, > "customer": { > "email": "john.doe@example.com", > "phone_number": "+4799999999" > } > }, > "token_provider": { > "payment_product_type": "dintero_psp.creditcard", > "token_types": ["payment_token"] > } > } > ``` The response will look like this: ```json theme={null} { "id": "T11223445.5cyWnV68vzJ1kYjZPrKWWm", "url": "https://checkout.test.dintero.com/v1/view/T11223445.5cyWnV68vzJ1kYjZPrKWWm" } ``` Redirect the customer to the url for them to confirm their card. ### Creating token while performing a purchase To store a customer's card information during the payment process, set `generate_payment_token` to `true` in the session configuration for the relevant payment provider. When creating the session, include the `configuration` object with the provider-specific settings: > [tab] payex.creditcard > > ```json theme={null} > { > "url": { > "return_url": "https://example.com/accept", > "callback_url": "https://example.com/callback?method=GET" > }, > "customer": { > "email": "john.doe@example.com", > "phone_number": "+4799999999" > }, > "order": { > "amount": 29990, > "currency": "NOK", > "vat_amount": 6000, > "items": [ > { > "line_id": "1", > "description": "Stablestol", > "quantity": 1, > "amount": 29990, > "vat_amount": 6000, > "vat": 25 > } > ], > "merchant_reference": "order-1" > }, > "configuration": { > "payex": { > "creditcard": { > "generate_payment_token": true, > "generate_recurrence_token": true > } > } > }, > "profile_id": "default" > } > ``` > [tab] bambora.creditcard > > ```json theme={null} > { > "url": { > "return_url": "https://example.com/accept", > "callback_url": "https://example.com/callback?method=GET" > }, > "customer": { > "email": "john.doe@example.com", > "phone_number": "+4799999999" > }, > "order": { > "amount": 29990, > "currency": "NOK", > "vat_amount": 6000, > "items": [ > { > "line_id": "1", > "description": "Stablestol", > "quantity": 1, > "amount": 29990, > "vat_amount": 6000, > "vat": 25 > } > ], > "merchant_reference": "order-1" > }, > "configuration": { > "bambora": { > "creditcard": { > "generate_payment_token": true > } > } > }, > "profile_id": "default" > } > ``` > [tab] dintero_psp.creditcard > > ```json theme={null} > { > "url": { > "return_url": "https://example.com/accept", > "callback_url": "https://example.com/callback?method=GET" > }, > "customer": { > "email": "john.doe@example.com", > "phone_number": "+4799999999" > }, > "order": { > "amount": 29990, > "currency": "NOK", > "vat_amount": 6000, > "items": [ > { > "line_id": "1", > "description": "Stablestol", > "quantity": 1, > "amount": 29990, > "vat_amount": 6000, > "vat": 25 > } > ], > "merchant_reference": "order-1" > }, > "configuration": { > "dintero_psp": { > "creditcard": { > "generate_payment_token": true > } > } > }, > "profile_id": "default" > } > ``` The generated payment token will be available in the transaction details after a successful payment. It can also be retrieved by calling get transaction details with `?includes=card.payment_token`. If recurrence tokenization is enabled for PayEx, get transaction details may also return a recurrence token with `?includes=card.recurrence_token`. See [create session] for more information. For `payex` (Swedbank Pay), it's also possible to disable CVC for returning payments if you have a dedicated agreement with Swedbank Pay. #### Save card checkbox (dintero_psp.creditcard) When using `dintero_psp.creditcard`, you can let the customer choose whether to save their card by adding `generate_payment_token_config` with a `save_card_checkbox` setting. This displays a checkbox in the checkout UI (see image below). ![Payment with save card checkbox](https://mintcdn.com/dintero-c3a7bfec/ek1h0boFqKSTUtqf/docs/assets/checkout/checkout-tokenization-save-card.png?fit=max\&auto=format\&n=ek1h0boFqKSTUtqf\&q=85\&s=6c141e59fd536c6037b99fe089d8f55e) > [!NOTE] > > * If `generate_payment_token` is `true` and `generate_payment_token_config` is **omitted**, the card is always tokenized (no checkbox shown). > * `save_card_checkbox: "opt_in"`: the checkbox is **unchecked** by default. The customer must actively check it to save their card. > * `save_card_checkbox: "opt_out"`: the checkbox is **checked** by default. The customer must actively uncheck it to prevent saving. **opt_in** (customer must actively choose to save their card): ```json theme={null} { "url": { "return_url": "https://example.com/accept", "callback_url": "https://example.com/callback?method=GET" }, "customer": { "email": "john.doe@example.com", "phone_number": "+4799999999" }, "order": { "amount": 29990, "currency": "NOK", "vat_amount": 6000, "items": [ { "line_id": "1", "description": "Stablestol", "quantity": 1, "amount": 29990, "vat_amount": 6000, "vat": 25 } ], "merchant_reference": "order-1" }, "configuration": { "dintero_psp": { "creditcard": { "generate_payment_token": true, "generate_payment_token_config": { "save_card_checkbox": "opt_in" } } } }, "profile_id": "default" } ``` **opt_out** (checkbox is checked by default, customer must uncheck to prevent saving): ```json theme={null} { "configuration": { "dintero_psp": { "creditcard": { "generate_payment_token": true, "generate_payment_token_config": { "save_card_checkbox": "opt_out" } } } } } ``` > [!NOTE] > > `generate_payment_token` must be set to `true` for `save_card_checkbox` to have any effect. [create session]: /api-reference/session/checkout_session_profile_post [payment token session]: /api-reference/session/checkout_payment_token_session_post # Tokenization error handling Source: https://docs.dintero.com/docs/checkout/tokenization-error-handling Handle Dintero card-token errors such as Visa and Mastercard "do not try again" responses and excessive reattempts when running merchant-initiated payments. > [!WARNING] > > **Tokenization must be activated on your account before you can create or charge card tokens.** > > Contact your Dintero account manager to have it enabled. Until it is activated, requests > that create or use a card token will fail. ### Do not try again & excessive reattempts In accordance with directives from Visa and Mastercard there are 2 different types of limitations in the amount of successive reattempts of previously failed transaction using `unscheduled_purchase` or `recurring_purchase`. One such limitation will be limiting the amount of successive reattempts of a previously failed transaction that can be done using creditcard based payment method within a specified period. The limitation in question varies based on the card brand: * MasterCard - 10 failed payment attempts allowed during a period of **24 hours**. * Visa - 15 failed payment attempts allowed during a period of **30 days**. > Note that all of the attempts have to get a failed response to be added to the > limit quota - if a transaction goes through successfully, the quota will reset. The other limitation is in the case that Visa or Mastercard gives such a response that is flagged as “Do Not Retry” in accordance to Visa and MasterCard regulations. This response is given in the cases that they deem the transaction to never be possible to be valid - as an example, if the card no longer exists, and thus there is no point in retrying. In these cases, the card will be blocked immediately and no further attempts are allowed. Both of these limitations are based on the combination of the acquiring agreement that the transaction was initiated from, and the PAN of the card that was used. That is, a card might be blocked because of "Excessive Reattempts" at a particular merchant, while being allowed more reattempts at another. Please note that in the case a new card is issued in place of an old expired one, the new card usually keeps the same PAN - meaning that if the old card was blocked, the new one will be as well (until the period resets). This marks the importance of having such a logic in place that limits reattempts before the block actually takes place - this is where the new, clearer response messages will help. > [!NOTE] > > Merchant is responsible for managing their retry policy for payments that > fail, and to not retry payments that fail with a `DO_NOT_RETRY` error. > Insufficient error handling will cause cards to be **blocked**. #### `payex.creditcard` authorization error example A 200 response will be returned if the pay request fails because of authorization error. The transaction will have status **FAILED** and more information about the cause can be found in the **AUTHORIZE** event ```json theme={null} { "id": "...", "status": "FAILED", "events": [ { "event": "INITIALIZE", "success": true }, { "event": "AUTHORIZE", "success": false, "error": { "type": "REJECTED_BY_ACQUIRER_POSSIBLE_FRAUD", "code": "payex:errorCode:REJECTED_BY_ACQUIRER_POSSIBLE_FRAUD", "message": "payex:errorDescription:Wrong card-no check digit response-code: 34", "result_code": "34" } } ] } ``` ### Prevent duplicate transactions Use the `Dintero-Feature-Toggles` header to prevent creating duplicate transactions. Including `strict-merchant-reference` value in the header will prevent creating duplicate transaction as it will require the `merchant_reference` to be **unique** within 24 hours. **headers** ```http theme={null} Dintero-Feature-Toggles: strict-merchant-reference Content-Type: application/json ``` **body** ```json theme={null} { "session": { "url": { "callback_url": "https://example.com/callback?method=GET" }, "customer": { "tokens": { "payex.creditcard": { "payment_token": "" } } }, "order": { "amount": 29990, "currency": "NOK", "vat_amount": 6000, "merchant_reference": "order-1" }, "configuration": {} }, "payment": { "payment_product_type": "payex.creditcard", "operation": "unscheduled_purchase" } } ``` A 400 response will be returned if `merchant_reference` was duplicated. ```json theme={null} { "session_id": "T11223445.5cyWnV68vzJ1kYjZPrKWWm", "error": { "message": "session.order.merchant_reference", "code": "DUPLICATE" } } ``` # Fetch and store payment tokens Source: https://docs.dintero.com/docs/checkout/tokenization-fetching-storing Retrieve a Dintero payment token after the customer completes card entry by polling the transaction with the includes query parameter and persist it securely. When the customer has completed filling in their card info, the `return_url` and `callback_url` will receive a request. When you get this request, the payment token will be stored on the transaction. Use [get transaction details] to retrieve the transaction, with the query-param `includes` to include the card tokens. **example**: * `?includes=card.payment_token` * `?includes=card.recurrence_token` The token will then be included in the card details, e.g. `card.payment_token`. The card data contains `expiry_date` (format `MM/YYYY`). When tokenization is used, `card.expiry_date` will be the expiration date of the card itself if available. If the card’s expiration date is unavailable, `card.expiry_date` will fall back to the token’s expiration date. > [!NOTE] > > Store the token internally in a secure manner. ## Fetching a card token You can look up a stored token directly with [get card token], which returns the token's current status and card details without needing to go through a transaction. ### Token status A card token has one of the following statuses: | Status | Description | | - | - | | `ACTIVE` | The card is active and can be used for payment. | | `INACTIVE` | The card has not been activated for payment yet. | | `SUSPENDED` | The card has been deactivated, for example if it's blocked. It can be reactivated later. | | `DELETED` | The card has been deleted. It can never become active again. | | `CANCELLED` | The token has been deleted by the card issuer and can no longer be used to transact, per the card network's rules. | ### Attempting payment with a token A newly created token isn't synced immediately, so [get card token] can return a `404` for a token that was just created even though the token itself is valid. ### External references for imported tokens When importing cards from another PSP/acquirer, we store the reference you used there as an external token reference. You can use this reference the same way you'd use a Dintero-issued token: * Pass it as `token_id` to [get card token] to look up the token using the old PSP's reference. * Pass it as the `payment_token` or `recurrence_token` value when creating a payment, instead of the Dintero-issued token. See [use a stored card token]. Note that if the same card appeared multiple times in the imported cards, these will refer to a single payment token within our system. It is also recommended to switch to using the token's actual ID and payment token values instead of the old reference. [get transaction details]: /api-reference/transactions/transactions_id_get [get card token]: /api-reference/card-tokens/card_tokens_token_id_get [use a stored card token]: /docs/checkout/tokenization-use-token # Use a stored card token Source: https://docs.dintero.com/docs/checkout/tokenization-use-token Charge a stored Dintero card token for customer-initiated and merchant-initiated payments, including subscriptions, recurring billing, and one-click checkout. > [!WARNING] > > **Tokenization must be activated on your account before you can create or charge card tokens.** > > Contact your Dintero account manager to have it enabled. Until it is activated, requests > that create or use a card token will fail. ### Customer initiated transactions To use the token in a new session for the same customer, put the token value in the session under `customer.tokens.payex.creditcard` or `customer.tokens.bambora.creditcard`. See [create session]. > [tab] payex.creditcard > > ```json theme={null} > { > "url": { > "return_url": "https://example.com/thankyou", > "callback_url": "https://example.com/callback" > }, > "order": { > "amount": 29990, > "currency": "NOK", > "merchant_reference": "merchants_order_number" > }, > "customer": { > "email": "john.doe@example.com", > "phone_number": "+4799999999", > "tokens": { > "payex.creditcard": { > "payment_token": "" > } > } > }, > "profile_id": "default" > } > ``` > [tab] bambora.creditcard > > ```json theme={null} > { > "url": { > "return_url": "https://example.com/thankyou", > "callback_url": "https://example.com/callback" > }, > "order": { > "amount": 29990, > "currency": "NOK", > "merchant_reference": "merchants_order_number" > }, > "customer": { > "email": "john.doe@example.com", > "phone_number": "+4799999999", > "tokens": { > "bambora.creditcard": { > "payment_token": "" > } > } > }, > "profile_id": "default" > } > ``` > [tab] dintero_psp.creditcard > > ```json theme={null} > { > "url": { > "return_url": "https://example.com/thankyou", > "callback_url": "https://example.com/callback" > }, > "order": { > "amount": 29990, > "currency": "NOK", > "merchant_reference": "merchants_order_number" > }, > "customer": { > "email": "john.doe@example.com", > "phone_number": "+4799999999", > "tokens": { > "dintero_psp.creditcard": { > "payment_token": "" > } > } > }, > "profile_id": "default" > } > ``` The response will look like this: ```json theme={null} { "id": "T11223445.5cyWnV68vzJ1kYjZPrKWWm", "url": "https://checkout.test.dintero.com/v1/view/T11223445.5cyWnV68vzJ1kYjZPrKWWm" } ``` Redirect the customer to the url for them to confirm the payment with `CVC`. ### Recurrence transactions To perform transactions without involving the customer, using a recurrence token, use `recurring_purchase` operation when calling the pay endpoint. Swedbank Pay uses a `recurrence_token` for these charges. Bambora and Dintero PSP do not issue recurrence tokens, so pass the `payment_token` instead. See [Token types](/docs/checkout/tokenization#token-types). To charge an Apple Pay token issued by Dintero PSP, put it in `customer.tokens.dintero_psp.applepay` and set `payment_product_type` to `dintero_psp.applepay`. The token must come from an Apple Pay payment where `configuration.dintero_psp.applepay.generate_payment_token` was `true`. See [Create a token](/docs/checkout/tokenization-create-token). If you send a card token with `dintero_psp.applepay`, Dintero returns `400` with the error `Token does not match payment_product_type`. This applies to both recurring and unscheduled transactions. With the access token, call [Create and pay merchant initiated session][post session pay] with the following body: > [tab] payex.creditcard > > ```json theme={null} > { > "session": { > "url": { > "callback_url": "https://example.com/callback?method=GET" > }, > "customer": { > "email": "john.doe@example.com", > "phone_number": "+4799999999", > "tokens": { > "payex.creditcard": { > "recurrence_token": "" > } > } > }, > "order": { > "amount": 29990, > "currency": "NOK", > "vat_amount": 6000, > "items": [ > { > "line_id": "1", > "description": "Stablestol", > "quantity": 1, > "amount": 29990, > "vat_amount": 6000, > "vat": 25 > } > ], > "merchant_reference": "order-1" > }, > "configuration": { > "auto_capture": false > } > }, > "payment": { > "payment_product_type": "payex.creditcard", > "operation": "recurring_purchase" > } > } > ``` > [tab] bambora.creditcard > > ```json theme={null} > { > "session": { > "url": { > "callback_url": "https://example.com/callback?method=GET" > }, > "customer": { > "email": "john.doe@example.com", > "phone_number": "+4799999999", > "tokens": { > "bambora.creditcard": { > "payment_token": "" > } > } > }, > "order": { > "amount": 29990, > "currency": "NOK", > "vat_amount": 6000, > "items": [ > { > "line_id": "1", > "description": "Stablestol", > "quantity": 1, > "amount": 29990, > "vat_amount": 6000, > "vat": 25 > } > ], > "merchant_reference": "order-1" > }, > "configuration": { > "auto_capture": false > } > }, > "payment": { > "payment_product_type": "bambora.creditcard", > "operation": "recurring_purchase" > } > } > ``` > [tab] dintero_psp.creditcard > > ```json theme={null} > { > "session": { > "url": { > "callback_url": "https://example.com/callback?method=GET" > }, > "customer": { > "email": "john.doe@example.com", > "phone_number": "+4799999999", > "tokens": { > "dintero_psp.creditcard": { > "payment_token": "" > } > } > }, > "order": { > "amount": 29990, > "currency": "NOK", > "vat_amount": 6000, > "items": [ > { > "line_id": "1", > "description": "Stablestol", > "quantity": 1, > "amount": 29990, > "vat_amount": 6000, > "vat": 25 > } > ], > "merchant_reference": "order-1" > }, > "configuration": { > "auto_capture": false > } > }, > "payment": { > "payment_product_type": "dintero_psp.creditcard", > "operation": "recurring_purchase" > } > } > ``` > [tab] dintero_psp.applepay > > ```json theme={null} > { > "session": { > "url": { > "callback_url": "https://example.com/callback?method=GET" > }, > "customer": { > "email": "john.doe@example.com", > "phone_number": "+4799999999", > "tokens": { > "dintero_psp.applepay": { > "payment_token": "" > } > } > }, > "order": { > "amount": 29990, > "currency": "NOK", > "vat_amount": 6000, > "items": [ > { > "line_id": "1", > "description": "Stablestol", > "quantity": 1, > "amount": 29990, > "vat_amount": 6000, > "vat": 25 > } > ], > "merchant_reference": "order-1" > }, > "configuration": { > "auto_capture": false > } > }, > "payment": { > "payment_product_type": "dintero_psp.applepay", > "operation": "recurring_purchase" > } > } > ``` ### Unscheduled transactions To perform transactions without involving the customer, MIT (merchant initiated) transactions use `unscheduled_purchase` operation when calling the pay endpoint. With the access token, call [Create and pay merchant initiated session][post session pay] with the following body: > [tab] payex.creditcard > > ```json theme={null} > { > "session": { > "url": { > "callback_url": "https://example.com/callback?method=GET" > }, > "customer": { > "email": "john.doe@example.com", > "phone_number": "+4799999999", > "tokens": { > "payex.creditcard": { > "payment_token": "" > } > } > }, > "order": { > "amount": 29990, > "currency": "NOK", > "vat_amount": 6000, > "items": [ > { > "line_id": "1", > "description": "Stablestol", > "quantity": 1, > "amount": 29990, > "vat_amount": 6000, > "vat": 25 > } > ], > "merchant_reference": "order-1" > }, > "configuration": { > "auto_capture": false > } > }, > "payment": { > "payment_product_type": "payex.creditcard", > "operation": "unscheduled_purchase" > } > } > ``` > [tab] bambora.creditcard > > ```json theme={null} > { > "session": { > "url": { > "callback_url": "https://example.com/callback?method=GET" > }, > "customer": { > "email": "john.doe@example.com", > "phone_number": "+4799999999", > "tokens": { > "bambora.creditcard": { > "payment_token": "" > } > } > }, > "order": { > "amount": 29990, > "currency": "NOK", > "vat_amount": 6000, > "items": [ > { > "line_id": "1", > "description": "Stablestol", > "quantity": 1, > "amount": 29990, > "vat_amount": 6000, > "vat": 25 > } > ], > "merchant_reference": "order-1" > }, > "configuration": { > "auto_capture": false > } > }, > "payment": { > "payment_product_type": "bambora.creditcard", > "operation": "unscheduled_purchase" > } > } > ``` > [tab] dintero_psp.creditcard > > ```json theme={null} > { > "session": { > "url": { > "callback_url": "https://example.com/callback?method=GET" > }, > "customer": { > "email": "john.doe@example.com", > "phone_number": "+4799999999", > "tokens": { > "dintero_psp.creditcard": { > "payment_token": "" > } > } > }, > "order": { > "amount": 29990, > "currency": "NOK", > "vat_amount": 6000, > "items": [ > { > "line_id": "1", > "description": "Stablestol", > "quantity": 1, > "amount": 29990, > "vat_amount": 6000, > "vat": 25 > } > ], > "merchant_reference": "order-1" > }, > "configuration": { > "auto_capture": false > } > }, > "payment": { > "payment_product_type": "dintero_psp.creditcard", > "operation": "unscheduled_purchase" > } > } > ``` > [tab] dintero_psp.applepay > > ```json theme={null} > { > "session": { > "url": { > "callback_url": "https://example.com/callback?method=GET" > }, > "customer": { > "email": "john.doe@example.com", > "phone_number": "+4799999999", > "tokens": { > "dintero_psp.applepay": { > "payment_token": "" > } > } > }, > "order": { > "amount": 29990, > "currency": "NOK", > "vat_amount": 6000, > "items": [ > { > "line_id": "1", > "description": "Stablestol", > "quantity": 1, > "amount": 29990, > "vat_amount": 6000, > "vat": 25 > } > ], > "merchant_reference": "order-1" > }, > "configuration": { > "auto_capture": false > } > }, > "payment": { > "payment_product_type": "dintero_psp.applepay", > "operation": "unscheduled_purchase" > } > } > ``` [post session pay]: /api-reference/payment/checkout_session_pay_post [create session]: /api-reference/session/checkout_session_profile_post # Transaction management Source: https://docs.dintero.com/docs/checkout/transaction-management Capture, refund, void, and update Dintero Checkout transactions, including partial captures and partial refunds, to settle orders correctly after payment. ## Capturing When you are ready to ship the order, the transaction can be captured. When capturing, the money will be transferred to the merchant's account. > [!NOTE] > > After authorizing the transaction, it needs to be captured within a certain amount of time. > See [https://www.dintero.com/knowledge-base/authorizations](https://www.dintero.com/knowledge-base/authorizations) for more details. The API allows for both a full amount capture and a partial amount capture. The amount to capture cannot be higher than the authorized amount. Partial capture can be used to capture parts of the total transaction amount when needed, e.g., if only parts of the entire order are shipped or for other reasons. Partial capture may be called as many times as required as long as there is a remaining authorized amount to capture. > [!NOTE] > > If the session contained an `order.shipping_option`, this will have been moved to the list of `items` in the transaction, and this is where you should specify the `shipping_option` when capturing. > [!WARNING] > > NB! Captures might fail for various reasons, so it's important to check that the response indicates a successful > capture. #### Request **`POST`** `/v1/transactions/{id}/capture` [Capture] ```json theme={null} { "amount": 29990, "capture_reference": "string", "items": [ { "line_id": "1", "amount": 29990 } ] } ``` > [!NOTE] > > According to regulations you should not capture a payment until the product or service is provided to the customer. For > more information, please see the \[Consumer Authority's Guidelines] for the standard sales conditions for consumer > purchases of goods over the internet. ## Updating authorization For transactions authorized with Klarna (`klarna.klarna`) or Billie (`klarna.billie`), it is possible to update the authorized amount after the initial authorization. This allows merchants to add items to an order before capture, for example, to upsell additional products. > [!NOTE] > > Updating the authorization is only supported for Klarna and Billie transactions that have not yet been fully captured. #### Request **`POST`** `/v1/transactions/{id}/authorization` [Update authorization] ```json theme={null} { "amount": 35990, "items": [ { "line_id": "1", "description": "Product A", "quantity": 1, "amount": 29990, "vat_amount": 5998, "vat": 25 }, { "line_id": "2", "description": "Extra item", "quantity": 1, "amount": 6000, "vat_amount": 1200, "vat": 25 } ] } ``` The `amount` field is the new total authorized amount. If the transaction already has items, the `items` field is required and must include the updated list of items, and the sum of `items[*].amount` must equal the new `amount`. For transactions without existing items, `items` is optional; when provided, the same sum rule applies. ### Backoffice To add items to an authorized Klarna or Billie transaction via Backoffice: 1. Navigate to the transaction (status must be **Authorized**) 2. In the **Order items** section, click **+ Add item** 3. Fill in the item details: description, quantity, unit price, and VAT % 4. Click **Update** The authorized amount is automatically updated to reflect the new total. ## Void/cancel If, for some reason, the order will not be fulfilled, you can cancel the transaction to release the money from the customer's account. A transaction can only be voided if it has not been captured. After the void is successful, the transaction status is changed to `AUTHORIZATION_VOIDED`. #### Request **`POST`** `/v1/transactions/{id}/void` [Void] #### Response ```json theme={null} { "id": "...", ... "status": "AUTHORIZATION_VOIDED" } ``` ## Refund If the order, or parts of it, are returned, the money can be refunded. The refund amount cannot be larger than the captured amount. > [!WARNING] > > NB! Refunds might fail for various reasons, so it's important to check that the response indicates a successful refund. #### Request **`POST`** `/v1/transactions/{id}/refund` [Refund] ```json theme={null} { "amount": 29990, "reason": "string", "items": [ { "line_id": "1", "amount": 29990 }] } ``` [Update authorization]: /api-reference/transactions/transaction_tid_extend_authorization_post [Capture]: /api-reference/transactions/transactions_id_capture_post [Void]: /api-reference/transactions/transactions_id_void_post [Refund]: /api-reference/transactions/transactions_id_refund_post [Consumer Authority's Guidelines]: https://www.forbrukertilsynet.no/english/guidelines/guidelines-the-standard-sales-conditions-consumer-purchases-of-goods-the-internet # Transaction state diagram Source: https://docs.dintero.com/docs/checkout/transaction-state-diagram Visual flow of Dintero Checkout transaction states (INITIALIZED, AUTHORIZED, CAPTURED, REFUNDED, VOIDED, FAILED, DECLINED) with allowed transitions. The flow diagrams show the transaction status transition after operations. A transaction is created initially with status `INITIALIZED` when the user initiates the payment in the Checkout window. ![transaction status states](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/transactionDiagramBig.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=8bfbd9493d614324c990138fc8d43bb6) # Two B2B invoice payments Source: https://docs.dintero.com/docs/checkout/two Offer Two B2B invoice payments inside Dintero Checkout to give business buyers a simple, high-conversion checkout with deferred payment terms. Two is a payment method tailored to handle business-to-business (B2B) payments. By adding Two into your Dintero checkout, you can offer customers a simple and high converting B2B payment method. ### Payment types | Payment Type | Description | Use Case | EHF/ Electronic Invoice support | | - | - | - | - | | `two.invoice_b2b` | Business-to-business invoicing | One-time invoices to companies. | Norway, Sweden, Denmark and Finland. | ### How it works 1. Customer selects "Two - Business Invoice" payment at checkout. 2. Billing information is collected (name, address, email, phone, country, organization number). 3. Order verification via company representatives (handled by Two). 4. A transaction is created in Dintero's system. 5. When the merchant captures the transaction, Two distributes the invoice to the customer. 6. Customer pays the invoice to Two via their bank. 7. Dintero settles the funds when they are received from Two. ### Configuration Enable the Two payment type in the session configuration when creating a checkout session. ```http theme={null} POST https://api.dintero.com/v1/accounts/{account_id}/payments/sessions-profile Authorization: Bearer Content-Type: application/json { "url": { "return_url": "https://example.com/accept", "callback_url": "https://example.com/callback", "merchant_terms_url": "https://example.com/terms.html" }, "order": { "amount": 50000, "currency": "NOK", "vat_amount": 10000, "items": [ { "amount": 50000, "quantity": 1, "line_id": "1", "description": "Consulting services", "vat": 25, "id": "item-1" } ], "merchant_reference": "order-123" }, "configuration": { "two": { "type": "payment_type", "invoice_b2b": { "type": "payment_product_type", "enabled": true, "days_until_due": 14 } }, "profile_id": "default" } ``` #### Configuration options | Option | Applies To | Type | Description | | - | - | - | - | | `days_until_due` | All types | Integer (0-365) | Number of days until the invoice is due. Default: 14 days. | > [!NOTE] > > See related documentation for more information about creating sessions: > > * [Create a session](/docs/checkout/create-session) > * [Checkout API reference](/api-reference/session/checkout_session_profile_post) ### Verification After the end user finishes the payment form in the Dintero checkout they are redirected to Two's *customer verification page*. The specific method Two employs (e.g., OTP via SMS/email, or Open Banking check) is determined dynamically by Two's risk assessment based on: * The representative's details * The buyer's company profile * The order amount If the customer completing the payment is not the correct stakeholder/legal representative of the company: * The customer completing the payment needs to verify their identity * A legal representative of the company must also verify. Two's hosted verification page will display a list of known legal representatives of the company. The customer can then contact one of those individuals and ask them to verify on their behalf. The legal rep receives a verification request (via SMS or email) and completes their own verification step. * The order is only approved by Two once both the customer and a legal representative have completed verification. The payment is not rejected outright. The buyer is given the opportunity to get a legal rep to co-verify. ### Transaction lifecycle Two transactions are automatically authorized upon successful verification. | State | Description | | - | - | | **AUTHORIZED** | This is the initial successful state. | | **CAPTURED** | Two will send an invoice to the customer's company. | | **FAILED** | Payment could not be created. | | **PARTIALLY_REFUNDED** | A partial refund has been issued. The remaining amount is still valid. | | **REFUNDED** | The full transaction amount has been refunded. | | **VOIDED** | The transaction has been cancelled before it was captured. | ```mermaid theme={null} stateDiagram direction TB [*] --> AUTHORIZED [*] --> FAILED AUTHORIZED --> CAPTURED: Transaction Captured AUTHORIZED --> VOIDED: Transaction VOIDED CAPTURED --> PARTIALLY_REFUNDED: Partial refund CAPTURED --> REFUNDED: Full refund / cancel ``` #### Refunds and cancellations * To cancel an invoice, cancel (void) the transaction while it is in the **AUTHORIZED** state. * Partial refunds can be issued while the transaction is in the **CAPTURED** state. * For each refund on a transaction, a *credit note* is created and sent to the customer's company. *** ### Invoice dates * **Invoice issue date**: The date of the capture. * **Invoice due date**: Issue date + `days_until_due` from capture (default: 14 days). *** ### Billing address requirements Two requires a billing address with all payment types. | Field | B2B | | - | - | | `first_name` | Required | | `last_name` | Required | | `address_line` | Required | | `postal_code` | Required | | `country` | Required (ISO 3166 alpha-2) | | `phone_number` | Required | | `email` | Required | | `business_name` | Required | | `organization_number` | Required | > [!NOTE] > > For Norway, the organization number is 9 digits. For Sweden, it is either 10 or 12 digits. ### Liability Unlike card-based payments, a `CAPTURED` status for Two does not mean the customer has paid. It means Two has sent the invoice to the customer's company. The customer still needs to pay the invoice via their bank. Funds are not guaranteed to arrive in the merchant's account until Two has collected payment and settled it to the merchant. If the customer does not pay, the merchant's receipt of funds depends on Two's collection process and the specific contract terms. # Updating a checkout session Source: https://docs.dintero.com/docs/checkout/updating-session Update an existing Dintero Checkout session when the cart items, total amount, or discounts change so the customer always sees the correct order summary. ### Modifying cart items, amounts, and discounts When the items of a cart, total amount or discounts are changed on a previously created session, the session must be updated with the newest changes. To update the session, first it needs to be locked. Locking the session is done by using the [Checkout Web SDK]. When the session is locked, updating the session can commence. Documentation for updating the session can be found [here](/api-reference/session/checkout_session_put). It's not possible to update a session after it's been completed. [Checkout Web SDK]: https://github.com/Dintero/Dintero.Checkout.Web.SDK#locking-the-session # Fast-track returning customer payments Source: https://docs.dintero.com/docs/checkout/use-cases/express-checkout Speed up checkout for returning customers with stored payment details, pre-filled addresses, and one-click payments using Dintero Express. Give returning customers a faster checkout by pre-filling their payment details and shipping address. Express checkout reduces friction, skips address forms, and lets customers complete purchases in just a few clicks, improving conversion rates for repeat buyers. Express checkout works on top of the standard Checkout session. You add an `express` configuration to the session, and Dintero handles pre-filling details and collecting the shipping address from the payment provider (e.g., Vipps). Your server receives a callback with the address so you can return available shipping options dynamically. ```mermaid theme={null} sequenceDiagram participant Customer as Returning customer participant Checkout as Checkout page participant Merchant as Your server participant API as Dintero API Merchant->>API: Create express session API->>Checkout: Display express checkout Customer->>Checkout: Confirm pre-filled details Checkout->>Merchant: Shipping address callback Merchant-->>Checkout: Available shipping options Customer->>Checkout: Select shipping & pay Checkout->>API: Payment completed API->>Merchant: Callback with transaction + shipping details ``` ## Integration steps **1. Add the express configuration** Create a checkout session and include an `express` section in the request body. This tells Dintero to show the streamlined express flow instead of the standard checkout. The `express` object configures which customer details to collect (shipping address, email, phone) and where to send the shipping address callback. See [Express checkout](/docs/checkout/express) for the full `express` object reference. **2. Implement the shipping address callback** When the customer confirms their address, Dintero sends a callback to your server with the address details. Your server responds with the available shipping options: name, price, and delivery estimate for each. This lets you calculate shipping dynamically based on the customer's actual address, rather than showing a fixed list. See [Shipping address callback](/docs/checkout/shipping-address-callback) for the request/response format. **3. Return shipping options** Your callback response includes an array of shipping options. Each option has an ID, display name, amount, and optional delivery details. The customer picks one in the checkout. You can also support [multiple shipments](/docs/checkout/shipping-options-multiple-shipments) if an order ships from multiple locations. See [Shipping options](/docs/checkout/shipping-options) for the full payload structure. **4. Handle discount codes (optional)** If your store supports discount codes, you can enable a discount code field in the express checkout. When the customer enters a code, Dintero sends it to your server for validation. You respond with the updated order total. See [Express discount codes](/docs/checkout/checkout-express-discount-code) for the configuration. **5. Handle the payment result** The callback includes the transaction status, the selected shipping option, and the customer's shipping address. Use this to fulfill the order and ship to the confirmed address. Capture, void, and refund through the [Transactions API](/docs/checkout/transaction-management). ## What's next > [card] [Express checkout](/docs/checkout/express) > > Full reference for the express session configuration. > [card] [Shipping options](/docs/checkout/shipping-options) > > Return dynamic shipping options via callback. > [card] [Shipping address callback](/docs/checkout/shipping-address-callback) > > Receive and validate the customer's address during checkout. > [card] [Update a session](/docs/checkout/updating-session) > > Modify the session after creation (e.g., after applying a discount). # Accept payments in person Source: https://docs.dintero.com/docs/checkout/use-cases/in-person-payments Accept card payments on physical terminals at retail locations using the same Checkout API you use for online payments. Accept card payments at physical retail locations using Dintero terminals. You create a checkout session that targets a specific terminal, and the customer taps, inserts, or swipes their card to pay. In-person payments reuse the same Checkout API, session profiles, and transaction management you already use for online payments. The only difference is that the session references a store and terminal. ```mermaid theme={null} sequenceDiagram participant POS as POS / Your server participant API as Dintero API participant Terminal as Payment terminal participant Customer as Customer POS->>API: Create session (store + terminal ID) API->>Terminal: Trigger payment on device Terminal->>Customer: "Tap, insert, or swipe" Customer->>Terminal: Present card Terminal->>API: Payment result API->>POS: Callback with transaction status ``` ## Integration steps **1. Set up your account for in-person payments** Contact Dintero to enable In-Person Payments on your account. You need a **payout destination** (the merchant entity that receives funds) with completed KYC verification. See [Terminal onboarding](/docs/checkout/in-person/terminal-onboarding) for the full setup process. **2. Register a store and terminal** In Backoffice, create a **store** linked to your payout destination, then register a **terminal** to the store. Each terminal gets a unique ID that you reference when creating sessions. You'll need three identifiers for every terminal payment: | Identifier | What it is | | - | - | | `payout_destination_id` | The merchant entity receiving funds | | `store.id` | The physical store location | | `terminal_id` | The specific payment terminal | **3. Create a payment profile** Create a [payment profile](/docs/checkout/payment-profiles) with **Card (Present)** enabled. You can enable it on its own, or alongside other payment methods on the same profile. **4. Create a terminal session** Send a `POST` to `/v1/sessions-profile` with the order details and the store/terminal identifiers. There is no hosted checkout page. Include `order.store.id`, `order.store.terminal_id`, and `order.store.payout_destination_id` in your request, and reference your in-person payment profile with `profile_id`. Add a `publish` push/terminal configuration to the session request to initiate the payment on the terminal. Set `configuration.channel` to `in_store` so the transaction is recorded as an in-store payment. See [Create a terminal session](/docs/checkout/in-person/creating-terminal-session) for the full payload. **5. Customer pays on the terminal** The terminal prompts the customer to tap, insert, or swipe their card. In-person payments are processed as a sale, so the transaction moves directly to `CAPTURED` on success. **6. Handle the result** Receive the transaction result via your `callback_url` and [webhooks](/docs/checkout/checkout-webhooks). Manage refunds and voids through the standard [Transactions API](/docs/checkout/transaction-management), just like online payments. ## What's next > [card] [In-person overview](/docs/checkout/in-person/overview) > > Detailed overview of how terminal payments work. > [card] [Terminal onboarding](/docs/checkout/in-person/terminal-onboarding) > > Set up payout destinations, stores, and terminals. > [card] [Create a terminal session](/docs/checkout/in-person/creating-terminal-session) > > Full payload reference and response handling. # Split payments across sellers Source: https://docs.dintero.com/docs/checkout/use-cases/marketplace-split-payments Automatically split each payment across multiple sellers or merchants. Built for marketplaces and platforms that need to distribute funds to many recipients. Run a marketplace or platform where payments need to be distributed to multiple sellers. Dintero Split Payout lets you onboard sellers, define how each payment is split, and automatically route funds to the right recipients after each transaction. The customer sees a single checkout. Behind the scenes, Dintero splits the captured amount according to the rules you define in the session. ```mermaid theme={null} sequenceDiagram participant Customer as Customer participant Checkout as Checkout page participant API as Dintero API participant Platform as Platform participant SellerA as Seller A participant SellerB as Seller B Platform->>API: Create session with split rules API->>Checkout: Display checkout Customer->>Checkout: Pay full amount Checkout->>API: Payment captured API->>Platform: Callback with transaction status API->>SellerA: Payout (split share) API->>SellerB: Payout (split share) ``` ## Integration steps **1. Activate Dintero Payout** Enable Dintero Payout on your account. This is the underlying service that handles fund distribution to multiple recipients. See [Activate payout](/docs/checkout/split-payment/activate-payout) for the activation process. **2. Onboard sellers as payout destinations** Each seller on your platform needs to be registered as a **payout destination**. This involves collecting their business details and completing KYC (Know Your Customer) verification through Dintero. You can onboard sellers through Backoffice or programmatically via the management API. See [Add payout destinations](/docs/checkout/split-payment/add-payout-destinations) for both approaches. **3. Create sessions with split rules** When creating a checkout session, include a `split` configuration that defines how the payment is distributed. Each split rule specifies a payout destination and the amount or percentage that recipient should receive. The customer sees a normal checkout and pays the full order amount. After capture, Dintero distributes the funds according to your split rules. See [Create a split session](/docs/checkout/split-payment/creating-split-session) for the payload structure. **4. Handle the payment result** The callback includes the transaction status and split details. Capture the transaction when the order is ready to ship, and Dintero distributes the funds to each seller's payout destination. Refunds are also split. When you refund a transaction, each seller's share is returned proportionally. **5. Monitor settlements and reports** Track payouts to each seller through settlement reports. You can view reports per payout destination to reconcile what each seller has been paid. See [Split reports](/docs/checkout/split-payment/split-reports) for report formats, and [Fund transfer](/docs/checkout/split-payment/fund-transfer) for manual transfers between destinations. **6. Test the integration** Use your sandbox account (`T` prefix) to verify that split rules are applied correctly. Create sessions with multiple payout destinations and confirm the split amounts in the transaction details. See [Testing split payments](/docs/checkout/split-payment/testing-split-payments) for test scenarios. ## What's next > [card] [Split Payout overview](/docs/checkout/split-payment/split-overview) > > How split payouts work and the steps to get started. > [card] [Activate payout](/docs/checkout/split-payment/activate-payout) > > Enable Dintero Payout on your account. > [card] [Add payout destinations](/docs/checkout/split-payment/add-payout-destinations) > > Onboard sellers and create payout destinations. > [card] [Create a split session](/docs/checkout/split-payment/creating-split-session) > > Build a session with split payment rules. # Accept payments online Source: https://docs.dintero.com/docs/checkout/use-cases/online-checkout Add a checkout to your website or app. Create a session, display the Dintero-hosted payment page, and handle the result. Add a payment checkout to your website or app. You create a session with the order details, display the Dintero-hosted checkout (embedded or as a redirect), and receive a callback when the customer has paid. This is the standard integration for any online store or service that needs to collect a one-time payment. ```mermaid theme={null} sequenceDiagram participant Merchant as Your server participant API as Dintero API participant Checkout as Checkout page participant Customer as Customer Merchant->>API: Create checkout session API-->>Merchant: Session ID + checkout URL Merchant->>Checkout: Redirect or embed checkout Customer->>Checkout: Select payment method & pay Checkout->>API: Payment completed API->>Merchant: Callback with transaction status Checkout->>Customer: Redirect to confirmation page ``` ## Integration steps **1. Create API credentials** In [Backoffice](https://backoffice.dintero.com/), go to **Settings > API clients** and create a new **Checkout client**. Save the Client ID and Client Secret. The secret is only shown once. Use your sandbox account (`T` prefix) while developing. Switch to production (`P` prefix) when you're ready to accept real payments. **2. Authenticate** Exchange your credentials for a bearer token using the OAuth 2.0 client credentials flow. The token is valid for 4 hours and is used in the `Authorization` header for all API calls. See [Authentication](/docs/checkout/checkout-client#authentication) for details. **3. Create a checkout session** Send a `POST` request to `/v1/sessions-profile` with the order details: items, amounts, currency, and URLs for the callback and customer redirect. The response returns a **session ID** and a **checkout URL** that you use to display the payment page. See [Create a session](/docs/checkout/create-session) for the full payload reference. **4. Display the checkout** Show the checkout to the customer. You have two options: * **Redirect**: send the customer to the Dintero-hosted checkout page. Minimal setup, no iframe. * **Embed**: render the checkout inside your page using the [Web SDK](https://github.com/Dintero/Dintero.Checkout.Web.SDK). More control over the experience. See [Embed vs redirect](/docs/checkout/embedVredirect) for a comparison. **5. Handle the payment result** After the customer pays, Dintero notifies you through two channels: | Channel | How | Use for | | - | - | - | | **callback_url** | Server-to-server GET request (retried up to 20 times) | Verify payment and fulfill the order | | **return_url** | Customer browser redirect (not guaranteed) | Show a confirmation page | Always verify the transaction via the callback. The browser redirect can fail if the customer closes the tab. See [Handling payment](/docs/checkout/after-payment) for transaction statuses and handling. **6. Manage transactions** After authorization, you can **capture**, **void**, or **refund** transactions through the Transactions API. Most integrations capture when the order is shipped. See [Transaction management](/docs/checkout/transaction-management) for available operations and the [state diagram](/docs/checkout/transaction-state-diagram) for how transactions move between statuses. ## What's next > [card] [Quickstart](/docs/checkout/quickstart) > > End-to-end walkthrough with code examples in cURL, Python, and Node.js. > [card] [Test data](/docs/checkout/checkout-testdata) > > Test cards and sandbox scenarios for verifying your integration. > [card] [Payment profiles](/docs/checkout/payment-profiles) > > Configure which payment methods are shown in the checkout. > [card] [Webhooks](/docs/checkout/checkout-webhooks) > > Subscribe to real-time transaction events. # Send payment links Source: https://docs.dintero.com/docs/checkout/use-cases/payment-links Send a checkout link to customers via SMS or email. Ideal for phone orders, invoicing, or any scenario where the customer isn't on your website. Send a payment link directly to a customer's phone via SMS or email. This is useful for phone orders, manual invoicing, remote sales, or any situation where the customer isn't browsing your website. You create a checkout session with the customer's phone number, and Dintero delivers the link automatically. The customer opens it, pays on the Dintero-hosted checkout page, and you receive the result through your normal callback flow. ```mermaid theme={null} sequenceDiagram participant Merchant as Merchant participant API as Dintero API participant SMS as SMS / Push participant Customer as Customer participant Checkout as Checkout page Merchant->>API: Create session (+ phone number) API->>SMS: Deliver payment link SMS->>Customer: "Pay here: checkout.dintero.com/..." Customer->>Checkout: Open link Customer->>Checkout: Select payment method & pay Checkout->>API: Payment completed API->>Merchant: Callback with transaction status ``` ## Integration steps **1. Choose how to send links** There are three ways to send payment links: | Method | Best for | | - | - | | **Payment Link in Backoffice** | Manual one-off payments, no code required | | **Payment profile setting** | Automatically send SMS for every session using a specific profile | | **API configuration** | Full control, enable SMS per session in your code | For the no-code approach, go to **Payment Link** in Backoffice, choose **Send by > SMS/Push**, and enter the phone number. No API integration needed. **2. Enable SMS in your payment profile (optional)** If you want SMS delivery for all sessions using a specific profile, open [Backoffice](https://backoffice.dintero.com/) and enable SMS on the payment profile. Every session created with that `profile_id` will automatically send a link. **3. Create a session with SMS delivery** For API-driven delivery, create a checkout session and include the customer's phone number and SMS configuration in the request body. Dintero sends the SMS as soon as the session is created. Include `order.amount`, `order.currency`, the customer's phone number, and your callback/return URLs as with any session. See [Payment link by SMS](/docs/checkout/payment-link-by-sms) for the full configuration options. > [!NOTE] > > SMS messages are not sent for test sessions (`T` prefix accounts). Use production credentials to verify SMS delivery. **4. Customer receives and pays** The customer receives an SMS or push notification with a link to the Dintero-hosted checkout page. They open it, select a payment method, and complete the payment. The experience is the same as any Dintero Checkout. **5. Handle the payment result** The result is delivered to your `callback_url` and through [webhooks](/docs/checkout/checkout-webhooks), just like any other checkout session. Capture, void, and refund through the [Transactions API](/docs/checkout/transaction-management). ## Set a payment deadline A payment link is a checkout session, so the link stays open until the session's `expires_at` time. If you do not set `expires_at`, Dintero closes the session 1 day after you create it. When you create a payment link in Backoffice, you choose the deadline instead: 1 day, 1 week, or 1 month. To set your own deadline, include `expires_at` when you [create the session from a payment profile](/api-reference/session/checkout_session_profile_post): ```json theme={null} { "profile_id": "default", "expires_at": "2026-12-01T22:59:59Z", "url": { "return_url": "https://example.com/accept", "callback_url": "https://example.com/callback" }, "order": { "amount": 29990, "currency": "NOK", "merchant_reference": "invoice-1234" } } ``` `expires_at` must be in the future and no more than 180 days after you create the session. Otherwise the request fails with `400 Bad Request`. ### What happens at the deadline * **New payments stop.** After `expires_at`, the checkout page no longer loads and the customer sees that the payment link has expired. * **Completed payments are not affected.** Expiry does not void or refund a transaction. An `AUTHORIZED` transaction stays authorized until you capture or void it, or until the authorization itself expires. See [Duration of authorizations](/docs/integrations/support/duration-of-authorizations). * **Payments in progress can still complete.** If the customer started paying before `expires_at` and the payment provider confirms the payment afterwards, Dintero still registers the transaction and sends your `callback_url`. Keep handling callbacks for a session after its deadline. Walley Checkout is the exception: Walley rejects the purchase when the session has expired. > [!WARNING] > > Do not use [Cancel session](/api-reference/session/checkout_session_cancel_post) to enforce a deadline when the customer may already have paid. Cancelling a session voids its transaction if the transaction is `INITIALIZED` or `AUTHORIZED`. Use `expires_at` instead, which stops new payments and keeps existing authorizations. ### Confirm that a payment link is closed The session has no single status field. Call [Get session](/api-reference/session/checkout_session_get) after the deadline and check these fields: | Field | What it tells you | | - | - | | `transaction_id` | Set when the customer has paid or a payment is being processed. Check the transaction status with the [Transactions API](/docs/checkout/transaction-management). | | `expires_at` | When the time is in the past, the customer can no longer open the payment link. | | `cancelled_at` | Set when the session was cancelled. | To close a session that has no `transaction_id` for good, call [Cancel session](/api-reference/session/checkout_session_cancel_post). The response includes `cancelled_at`. If a payment that was in progress is authorized after you cancel, Dintero voids or refunds it automatically, so it never stays reserved on the customer's account. ## What's next > [card] [Payment link by SMS](/docs/checkout/payment-link-by-sms) > > Detailed configuration for Backoffice, payment profiles, and the API. > [card] [Payment in app](/docs/checkout/payment-in-app) > > Embed checkout in a native mobile app with deep links. > [card] [Hosted payment pages](/docs/checkout/payment-hosted) > > Skip the Dintero Checkout and complete payment via the Vipps or MobilePay hosted payment page. # Set up recurring payments Source: https://docs.dintero.com/docs/checkout/use-cases/subscriptions Charge customers on a recurring basis using tokenized cards. Collect payment details once, then bill automatically for memberships, SaaS, or any repeating service. Sell memberships, subscriptions, or any service that bills on a schedule. The customer pays once through a normal checkout, Dintero tokenizes their card, and you use the token to charge them again without requiring another checkout. You manage the billing schedule on your server. Dintero handles the secure card storage and recurring charges. ```mermaid theme={null} sequenceDiagram participant Merchant as Your server participant API as Dintero API participant Checkout as Checkout page participant Customer as Customer Merchant->>API: Create session (request token) API->>Checkout: Display checkout Customer->>Checkout: Enter card details & pay Checkout->>API: Payment authorized + token created API->>Merchant: Callback with transaction + token Note over Merchant,API: Recurring charge (days/weeks/months later) Merchant->>API: Create session with stored token API-->>API: Charge card (no customer interaction) API->>Merchant: Callback with transaction status ``` ## Integration steps **1. Enable tokenization** Contact your Dintero account manager to enable card tokenization on your account. This is required before you can store card details for future use. **2. Collect payment and create a token** Create a checkout session with `generate_payment_token: true` or `generate_recurrence_token: true`, depending on your payment provider and token type. The customer goes through the normal checkout flow, entering card details and completing the first payment. On success, Dintero returns a **recurrence token** or **payment token** alongside the transaction. The token type depends on your payment provider. See [Create a token](/docs/checkout/tokenization-create-token) for the session configuration. **3. Store the token** Save the token ID on your server, associated with the customer. This token represents the customer's stored card and is used for all future charges. See [Fetch and store tokens](/docs/checkout/tokenization-fetching-storing) for how to retrieve tokens from the transaction. > [!WARNING] > > Tokens are sensitive credentials. Store them securely on your server. Never expose them to the client. **4. Charge the customer on schedule** When a billing cycle is due, create a new checkout session with the stored token. The payment is processed server-to-server. The customer does not need to interact with a checkout page. If the charge fails (e.g., expired card, insufficient funds), you can notify the customer and prompt them to update their payment method through a new checkout session. See [Use a stored token](/docs/checkout/tokenization-use-token) for the recurring charge payload. **5. Handle upgrades, downgrades, and cancellations** Subscription changes are managed on your server. To change the billing amount, adjust the `order.amount` in the next recurring session. To cancel, stop creating new sessions. See the [Subscription example](/docs/checkout/subscription-example) for a complete walkthrough with tiered memberships. ## Token types | Token type | Provider | Use case | | - | - | - | | **recurrence_token** | Swedbank Pay | Merchant-initiated recurring charges without customer interaction | | **payment_token** | Swedbank Pay, Bambora, Dintero PSP | One-click payments and stored card charges | ## What's next > [card] [Tokenization overview](/docs/checkout/tokenization) > > How card tokenization works, supported providers, and token types. > [card] [Create a token](/docs/checkout/tokenization-create-token) > > Configure the first session to request a token. > [card] [Use a stored token](/docs/checkout/tokenization-use-token) > > Charge a customer using their saved token. > [card] [Subscription example](/docs/checkout/subscription-example) > > End-to-end example with tiered memberships and upgrades. # Validating callbacks Source: https://docs.dintero.com/docs/checkout/validating-callbacks Open firewalls for Dintero callback IPs and verify the authenticity of incoming Checkout callbacks so only legitimate session events update your backend. ## Opening firewalls for callbacks Callbacks from checkout sessions will be sent from one of these IPs: * `34.241.230.119` * `34.242.13.162` If you're using a firewall, traffic from these IPs should be let through. These IPs apply to session callbacks. To receive account-wide event notifications instead, see [Webhooks](/docs/checkout/webhooks). ## Validating callbacks with signature Use [POST /v1/admin/signature](/checkout-api/secrets/admin_signature_post) to create a secret. The following callbacks from Dintero will then include a header named **Dintero-Signature**, and your backend can verify it: The signature secret belongs to the account your access token was issued for. Sandbox (`T` prefix) and production (`P` prefix) accounts are separate, so create one secret on each account and store them separately in your backend. The account ID is also part of the signed payload. See [Sandbox vs production](/docs/checkout/quickstart#sandbox-vs-production). Callbacks from Dintero will include a header named **Dintero-Signature**, and your backend can now implement signature verification for this. * The session callback (`url.callback_url`) * The shipping address callback (`express.shipping_address_callback_url`) * The discount codes callback (`express.discount_codes.callback_url`) The signature covers the timestamp, account ID, HTTP method, hostname, path, and sorted query parameters of the callback URL. It does **not** cover the request body. ### Example code for validating signature To validate the signature received in the **Dintero-Signature** header * Note that spaces in query parameters must be encoded with `+` (not `%20`) before the signature is created * The query parameters must be sorted For the shipping address and discount codes callbacks, `method` is `POST`, and the URL is the callback URL exactly as you set it on the session. ```js JavaScript lines theme={null} const assert = require("node:assert/strict"); const crypto = require("node:crypto"); const account_id = "T12345678"; const secret = "apikeysecret"; const createSignature = (requestUrl, method, timestamp) => { const dataUrl = new URL(requestUrl); const { hostname, pathname } = dataUrl; const params = dataUrl.searchParams; params.sort(); const query = params.toString(); const payload = `${timestamp}\n${account_id}\n${method}` + `\n${hostname}\n${pathname}\n${query}`; const signature = crypto .createHmac("sha256", secret) .update(payload, "utf8") .digest("hex"); return `t=${timestamp},` + `v0-hmac-sha256=${signature}`; }; const verifySignature = (signatureHeader, method, requestUrl) => { const parts = signatureHeader.split(","); const timestamp = parseInt(parts[0].split("=")[1]); const now = Math.floor(new Date().getTime() / 1000); assert.ok( // reject callbacks older than 5 minutes now - timestamp < 5 * 60, ); const trusted = Buffer.from( createSignature(requestUrl, method, timestamp), "ascii", ); const untrusted = Buffer.from(signatureHeader, "ascii"); assert.ok(crypto.timingSafeEqual(trusted, untrusted)); console.log("signature valid"); }; ``` ## How to view the callback sent and received Sometimes, small unforeseen difficulties might occur when implementing the signature check. For example, if you successfully create a transaction from a checkout session but the signature check fails on the received callback, this might be for you. To provide a better overview of the request sent and response received, the Backoffice platform offers a view at the bottom of each individual transaction page. This view includes any callbacks sent and received. ### 1. Login to [backoffice](https://backoffice.dintero.com/), then follow this interactive slide-show [Dintero Backoffice](https://demo.arcade.software/Zo6CYKuX4eqiqJBFmdzf?embed) # Vipps mobile payments Source: https://docs.dintero.com/docs/checkout/vipps Accept Vipps, the most popular Norwegian payment app, online and in person through Dintero Checkout with one-click in-app approvals. Vipps is a Norwegian mobile payment application that allows customers to approve payments in the Vipps app. It is widely used across Norway and supports both online and in-person payments. ### How it works 1. Customer selects Vipps at checkout and enters their phone number. 2. A payment request is sent to the customer's Vipps app. 3. The customer authenticates and approves the payment in the app. 4. The transaction is authorized and the merchant receives a callback. 5. The merchant captures the transaction to complete the payment. 6. Funds are settled to the merchant through the configured settlement schedule. ### Liability Vipps is a wallet payment method where the customer actively approves the payment from the Vipps app. Payments are authenticated using device biometrics (Face ID, Touch ID) or device passcode. Vipps then passes a network token for the card data directly to Dintero. For Visa this will generally be considered Strong Customer Authentication (SCA), so the liability is on the card issuer, not the merchant. For Mastercard liability will always be on the merchant as they don't send a network token that Mastercard accepts as having SCA. * **Chargeback risk**: Transactions are subject to card network chargeback rules. Customers can dispute charges through their card issuer (e.g., fraud disputes, items not received), following the same process and liability rules as regular card payments. * **Funds guarantee**: Vipps transactions go through a standard card authorization flow. An `AUTHORIZED` transaction means funds have been reserved at the card network level, and a `CAPTURED` transaction means funds are on their way to settlement. * **ECI**: Merchants can inspect the `card.eci` field on an authorized transaction before capturing to determine the authentication level and resulting liability. A value of `05` (Visa) or `02` (Mastercard) indicates full SCA with liability shift to the issuer. `06`/`01` indicates authentication was attempted. `07`/`00` indicates no authentication was performed and the merchant bears fraud liability. # Walley B2B invoice payments Source: https://docs.dintero.com/docs/checkout/walley-b2b Implement Walley B2B invoice payments with Dintero Checkout Express to capture an approved business shipping address that meets Walley's invoicing requirements. ### Special considerations When accepting Walley B2B invoice payments it is important to implement Dintero Checkout Express to get an approved shipping address that will be accepted by Walley. For Walley B2B Invoice payments Dintero Checkout Express will use Walleys own business registry to fetch shipping and billing information about the customers company. It is important that the session is created without a complete company address, as the checkout then skips the company lookup . The `session.order.shipping_address.country` and `session.order.shipping_address.organization_number` can be set to prefill those values in the company lookup form. See the [Dintero Checkout Express documentation](/docs/checkout/express) for more information on how to implement this. ### Liability Unlike card-based payments, Walley B2B invoice payments do not reserve or guarantee funds at the time of authorization. A captured transaction means Walley has issued an invoice to the customer's company, but the customer still needs to pay it via their bank. Funds are not guaranteed to arrive in the merchant's account until Walley has collected payment and settled it. If the customer does not pay, the merchant's receipt of funds depends on Walley's collection process and the specific contract terms. # Subscribe to and verify webhooks Source: https://docs.dintero.com/docs/checkout/webhooks Receive real-time event notifications from Dintero by subscribing to webhooks via API or Backoffice for transactions, settlements, and other platform events. Verify and authenticate deliveries with a shared secret and HMAC-SHA1 signature. A webhook is an HTTP request that Dintero sends to a URL you control whenever a subscribed event happens, such as a transaction being authorized or a settlement being created. Instead of polling the API for changes, your server receives the event data as soon as the event occurs. Webhooks are configured per account and can deliver many event types. For events tied to a single Checkout session, you can also use the session `callback_url`. See [Validating callbacks](/docs/checkout/validating-callbacks) for that flow. > [!NOTE] > > The `checkout_authorization` event delivers the same payload as the session `callback_url`. Use a webhook subscription when you want account-wide delivery instead of configuring a `callback_url` on every session. ## Set up webhooks via API Create a subscription with [POST /accounts/\{aid}/hooks/subscriptions](/webhooks-api/subscriptions/aid_source_hooks_post). In the request you define: * `config.url`: the public HTTPS URL that receives the event payloads * `events`: the list of event types to subscribe to * `config.secret`: an optional secret used to sign deliveries (see [Verify event signature](#verify-event-signature)) When you create a subscription, Dintero sends a ping event so you can confirm the endpoint is set up correctly. For the full list of event types and the payload of each, see the [Webhooks API reference](/webhooks-api/subscriptions/aid_source_hooks_post). ## Set up webhooks via Backoffice In Dintero Backoffice, go to **Settings → Webhooks** to create and manage subscriptions without using the API. ## Verify event signature To confirm that a request originated from Dintero, create the subscription with an `HMAC-SHA1` secret. Each delivery then includes an `event-signature` header containing the HMAC-SHA1 digest of the request body, computed with your secret. Dintero does not use a TLS or signing certificate to sign webhooks. Authenticity is verified with a shared **secret** (`config.secret`) that you set when creating the subscription, using HMAC-SHA1. > [!NOTE] > > The webhook subscription API signs deliveries with HMAC-SHA1. This is separate from the Checkout `callback_url` signature, which uses HMAC-SHA256. See [Validating callbacks](/docs/checkout/validating-callbacks). Compute the digest over the raw request body and compare it to the header value: ```typescript theme={null} const crypto = require("node:crypto"); // `rawBody` must be the exact bytes received, not a re-serialized object. // In Express, capture them with the json parser's `verify` hook: // express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }) const verifyEventSignature = (rawBody, secret, eventSignature) => { if (typeof eventSignature !== "string") { return false; } const calculatedEventSignature = crypto .createHmac("sha1", Buffer.from(secret)) .update(rawBody) .digest("hex"); const received = Buffer.from(eventSignature, "hex"); const calculated = Buffer.from(calculatedEventSignature, "hex"); return ( received.length === calculated.length && crypto.timingSafeEqual(received, calculated) ); }; ``` > [!WARNING] > > Verify the signature against the **raw request body bytes**, exactly as received. Re-serializing the parsed JSON (for example with `JSON.stringify(req.body)`) can change whitespace or key order, producing a digest that does not match and rejecting legitimate deliveries. > [!TIP] > > Decode both hex signatures to buffers and compare them with a constant-time function such as `crypto.timingSafeEqual` rather than `===`, so the check does not leak timing information. Guard against a missing header and unequal lengths first, since `timingSafeEqual` throws when the buffers differ in length. # Glossary Source: https://docs.dintero.com/docs/glossary Definitions of Dintero terms used across the documentation, including wallet, session, transaction, payment profile, payment product type, split payout, and account ID. ## Dintero Checkout | Term | Definition | | - | - | | **Account ID** | The identifier for your Dintero account, used in API paths as `{account_id}` or `{aid}`. The first character is the environment: `T` for sandbox, `P` for production. The same account has both, for example `T12345678` and `P12345678`. | | **Session** | The object you create to start a checkout. Holds the order amount, currency, line items, available payment methods, and the return and callback URLs. Creating one gives you a URL to open or embed. A session results in at most one transaction. See [Creating a session](/docs/checkout/create-session). | | **Transaction** | The record of an actual payment, created when the customer completes the checkout. Holds the payment method used, card details, and status, and is the object you capture, refund, or void. The session references it through `transaction_id`. See [Handling payment](/docs/checkout/after-payment). | | **Payment profile** | A named payment configuration stored on your account, referenced by `profile_id` when creating a session. Decides which payment methods the session offers, so you can change methods in Backoffice without changing integration code. Most accounts have a `default` profile. See [Payment profiles](/docs/checkout/payment-profiles). | | **`merchant_reference`** | Your own reference for the order, set on the session and carried through to the transaction and the callback. Use it to match Dintero's records against your order system. | | **Amount** | Every monetary amount in the API is given in the smallest unit of the currency, so `33890` is 338.90 NOK. This applies to order amounts, line items, shipping, captures, and refunds. | | **`line_id`** | The identifier of a line on the order, unique across all items. You reference it when capturing or refunding part of an order, and it is required for some payment methods. | | **Checkout Express** | A checkout flow where Dintero collects the customer's details and shipping choice inside the checkout, enabled with an `express` object on the session. Some features, such as shipping callbacks and [external payment methods](/docs/checkout/dintero-external), only work in Express sessions. See [Checkout Express](/docs/checkout/express). | | **`callback_url`** | The machine-to-machine notification Dintero sends when a payment completes, as an HTTPS `GET` with `transaction_id`, `session_id`, `merchant_reference`, and `time`. Retried up to 20 times. This is the reliable signal that a payment happened. See [Handling payment](/docs/checkout/after-payment#callback_url). | | **`return_url`** | The URL the customer's browser is redirected to after they complete or cancel the payment. Use it to show a confirmation page, not to record the payment: the customer may lose connectivity or close the browser first. Your integration must handle it arriving in parallel with `callback_url`. | | **Backoffice** | Dintero's merchant web application at [backoffice.dintero.com](https://backoffice.dintero.com/), where you manage account settings, transaction data and products associated with a Dintero account. | ## Payment lifecycle | Term | Definition | | - | - | | **Authorization** | The step where the provider reserves money on the customer's account without moving it. A successful payment leaves the transaction `AUTHORIZED`. The money is not yours until you capture it, and an authorization expires if it is not captured in time. | | **Capture** | Transferring the authorized money to your account, normally when you ship the order. Can be partial and repeated, up to the authorized amount. See [Transaction management](/docs/checkout/transaction-management). | | **Void** | Cancelling an authorized transaction so the reserved money is released back to the customer. Use it when the order will not be fulfilled and nothing has been captured. See [Void/cancel](/docs/checkout/transaction-management#void-cancel). | | **Refund** | Returning captured money to the customer, in full or in part. Cannot exceed the captured amount. To release an authorization that was never captured, void it instead. See [Refund](/docs/checkout/transaction-management#refund). | | **Transaction status** | The state a transaction is in after completion: `AUTHORIZED`, `ON_HOLD`, `CAPTURED`, `FAILED`, or `DECLINED`. See the [transaction state diagram](/docs/checkout/transaction-state-diagram). | | **Payout** | The transfer of captured funds from Dintero to your bank account. | | **Settlement report** | The report generated for each payout to your bank account, used for accounting and reconciliation. Found in Backoffice under **Reports** → **Payout reports**. See [Settlement reports](/docs/checkout/payout-reports-introduction). | ## Payment methods | Term | Definition | | - | - | | **Payment method** | The way the customer pays: card, wallet, invoice, and so on. The docs also use "payment type" and "payment product" for this, so treat the three as the same concept. The precise machine-readable identifier is the payment product type. | | **Payment product type** | The identifier for a specific payment method, written as `provider.method`. The part before the dot is the provider handling the payment, the part after is the method. Examples: `dintero_psp.creditcard`, `dintero_psp.applepay`, `klarna.klarna`, `swish.swish`. Used to configure a session and to filter what the checkout displays with [`show_payment_type`](/docs/checkout/show-payment-type). | | **Wallet** | A payment method where the customer pays from an app or a device wallet instead of typing card details: [Apple Pay](/docs/checkout/apple-pay/apple-pay-overview), [Google Pay](/docs/checkout/google-pay/google-pay-overview), [Vipps](/docs/checkout/vipps) (Norway), MobilePay (Denmark), and Swish (Sweden). Configured like any other payment method and identified by payment product types such as `dintero_psp.applepay`. Not to be confused with the Wallet service. | | **Wallet service** | A separate product under Loyalty & Virtual Cards that issues and redeems gift cards with a stored balance. Lives under `/v1/accounts/{aid}/wallets/`, uses the `read:wallets` and `write:wallets` scopes, and emits `wallet_transaction` webhook events. Nothing to do with wallet payment methods. See [Create gift cards](/docs/loyalty/wallet-create-gift-card). | | **BNPL** | Buy now, pay later. Invoice and installment methods where a provider pays you up front and collects from the customer later, such as Klarna, Walley, Billie, Kravia, Two, and Instabank. See [test data](/docs/checkout/checkout-testdata). | | **EHF** | The Norwegian electronic invoicing format. Relevant for B2B invoice methods that support sending electronic invoices, such as [Two](/docs/checkout/two). | | **Gift card** | A card with a stored balance, issued and redeemed through the Wallet service and spendable in Dintero Checkout or your own payment flow. Unrelated to wallet payment methods. See [Gift cards](/docs/checkout/gift-cards). | | **External payment method** | A payment method you handle yourself, shown in the checkout under your own label and pay button. Express sessions only. See [External payment method](/docs/checkout/dintero-external). | | **EMD** | Extra merchant data, additional order detail sent to Klarna for travel, events, marketplaces, and digital goods to improve order acceptance. See [Klarna EMD attachments](/docs/checkout/klarna-emd). | | **POS** | Point of sale, the in-store checkout system. Dintero's in-person payments and the Loyalty services are commonly integrated from a POS. See [In-person payments](/docs/checkout/in-person/overview). | | **IPP** | In-person payments, accepting payments on physical Dintero terminals. See [In-person payments](/docs/checkout/in-person/overview). | > [!WARNING] > > **"Wallet" means two unrelated things at Dintero.** Enabling a wallet payment method does not require the Wallet service, and the `wallets` scopes are not needed for access to wallet payment methods. ## Cards and security | Term | Definition | | - | - | | **PSP** | Payment service provider, the party that processes the payment with the card networks or the payment method. Dintero Checkout routes to several PSPs, and the provider prefix in a payment product type tells you which one handles a given method. `dintero_psp` is Dintero's own. | | **Acquirer** | The institution that processes card payments on the merchant's behalf and moves the funds. Dintero is an acquirer. | | **Issuer** | The bank that issued the customer's card and that approves or declines the payment. | | **Cardholder** | The person the card belongs to. See [PCI DSS compliance](/docs/checkout/merchant-pci-dss-compliance) for what you may and may not store about them. | | **3-D Secure (3DS)** | The authentication step where the card issuer verifies the cardholder during a card payment, often with an app or a one-time code. See the [card test data](/docs/checkout/testdata/dintero-psp/checkout-dintero-cards-testdata) for how to trigger 3DS flows in sandbox. | | **SCA** | Strong Customer Authentication, the level of authentication that shifts fraud liability from you to the issuer. Achieved through 3-D Secure, and for wallets through the device authentication in the wallet app. | | **Liability shift** | Who carries the cost if a payment turns out to be fraudulent. With full SCA the issuer carries it, without it you do. Wallet payments differ by card scheme: see [Vipps](/docs/checkout/vipps) for a worked example. | | **ECI** | Electronic Commerce Indicator, the field on an authorized transaction (`card.eci`) that tells you what level of authentication was performed and therefore who carries the liability. Values differ per card scheme. See [Vipps](/docs/checkout/vipps). | | **Network token** | A card scheme issued stand-in for the real card number, passed to Dintero by wallets such as Vipps instead of the raw card data. | | **PCI DSS** | Payment Card Industry Data Security Standard, the security standard for handling card data. Dintero is a certified Level 1 Service Provider, which keeps your own scope small. See [PCI DSS compliance](/docs/checkout/merchant-pci-dss-compliance). | | **SAQ** | Self-Assessment Questionnaire, how merchants document PCI DSS compliance. Because Dintero handles all card data, most merchants qualify for **SAQ A**, the simplest one. | | **PAN** | Primary Account Number, the card number itself. A replacement card usually keeps the same PAN, which matters when handling stored tokens. | | **CVC** | The security code on the card, which the payer enters to complete a purchase. Still required when paying with a stored payment token in the checkout. | | **MIT** | Merchant initiated transaction, a payment you trigger without the payer being present, for example an unscheduled charge on a stored card. Requires approval from your account manager. See [Tokenization](/docs/checkout/tokenization). | | **Payment token** | A stored stand-in for a card that prefills the card in the checkout, where the payer still enters the CVC. With approval it can also be used for merchant initiated transactions. See [Tokenization](/docs/checkout/tokenization). | | **Recurrence token** | A stored stand-in for a card that charges it without payer interaction, for recurring billing. Only some providers issue these. Providers that do not, such as Dintero PSP and Bambora, use payment tokens for recurring payments instead. | | **OTP** | One-time password, a single-use code sent to the customer to confirm their identity during a payment. | | **SSN** | Social security number, the national identity number used to identify a customer for some invoice and financing methods in the Nordics. | ## Split payout | Term | Definition | | - | - | | **Split payout** | Splitting a single Checkout payment across multiple merchants, for marketplaces and platforms. See [Split payout overview](/docs/checkout/split-payment/split-overview). | | **Seller** | A merchant you onboard onto your platform so they can receive part of a split payment. | | **Payout destination** | The registered account a seller's share of a payment is paid out to, referenced by `payout_destination_id`. Requires completed KYC. See [Add payout destinations](/docs/checkout/split-payment/add-payout-destinations). | | **Merchant of record** | The party legally responsible for a transaction. Platforms must specify it on each order with `store.payout_destination_id`. See [Creating a split session](/docs/checkout/split-payment/creating-split-session). | | **Marketplace / Platform** | The two split payout account types. Only platforms have to specify the merchant of record on each transaction. Dintero tells you which one you are during onboarding. | | **KYC** | Know Your Customer, the verification of a business and its owners that Dintero's KYC department runs before a payout destination is approved. | | **Fund transfer** | Moving money from one seller's payout destination to another, processed asynchronously and shown in the settlement report. See [Fund transfer](/docs/checkout/split-payment/fund-transfer). | # Welcome to Dintero Source: https://docs.dintero.com/docs/index Dintero is a unified commerce platform for payments, loyalty, order management, and partner integrations. Find API references, integration guides, and code examples. Dintero documentation Dintero is a unified commerce platform that brings payments, loyalty, order management, and partner tools together. Whether you're building an online store, a marketplace, or a point-of-sale system, Dintero handles the financial infrastructure so you can focus on your product. > [card] [Using WooCommerce, Shopify, Magento, or another e-commerce platform?](/docs/integrations/plugins) > > You don't need to build a custom integration. Go to [Plugins & Integrations](/docs/integrations/plugins) for setup instructions. ## Get started with payments > [card] [Quickstart](/docs/checkout/quickstart) > > Go from zero to your first payment in minutes. > [card] [Payments introduction](/docs/checkout/index) > > Introduction to Dintero Checkout, our hosted payment solution. ## Other products [Loyalty & Virtual Cards Manage customer profiles, run discount and loyalty programs, store digital receipts, and issue gift cards.](/docs/loyalty/getting-started) [Order Management Create and track orders independently of payment. Manage the full lifecycle from draft through authorization, capture, and refund.](/docs/order-management/overview) [Partners Automate merchant onboarding, configure payment settings, and pull reports on behalf of your merchants through the Partner API.](/docs/partners/partners) # Connect your accounting system Source: https://docs.dintero.com/docs/integrations/accounting-system Integrate Dintero Checkout with your accounting system to automatically send sales data for reconciliation, reporting, and financial management. Connect your accounting system to Dintero to automate reconciliation and reporting. There are two ways to integrate, depending on how much detail you need in your books. ![Dintero Backoffice accounting page](https://mintcdn.com/dintero-c3a7bfec/5SNT3w02xCre3YZI/docs/assets/backoffice/accounting.png?fit=max\&auto=format\&n=5SNT3w02xCre3YZI\&q=85\&s=2b3dddd148fa9411401332d2ecd06cf7) ## Supported accounting systems Dintero connects to Nordic accounting and ERP systems through its partners, including: > [card] Tripletex > [card] Visma > [card] Fortnox > [card] 24SevenOffice > [card] DNB Regnskap > [card] SpareBank 1 > [card] PowerOffice > [card] Xledger > [card] Unimicro > [card] Fiken > [card] Azets Complete > [card] Eika These integrations are provided by trusted third-party partners such as [eMonkey](https://www.emonkey.no/integrasjoner/dintero) and others. ## Automate payout reporting Payout reporting transfers settlement and fee data to your accounting system without any technical setup. It is included at no extra cost. This lets you: * Reconcile payouts from your online store with bank deposits * Match payout data and fees in your accounting system * Automate file-based routines for faster end-of-month reporting **1. Open accounting settings** In [Dintero Backoffice](https://backoffice.dintero.com), go to **Settings** > **Accounting**. **2. Select a format or provider** Choose the file format or provider that matches your accounting system. **3. Choose where to send reports** Enter the destination for the reports, such as the account-specific email address for your accounting system. Once configured, Dintero sends payout reports automatically. No further action is required. ## Full integration per order If you need each order, transaction, and fee matched directly in your accounting system (for example, to create vouchers per order), this is handled through a third-party integration partner. This includes: * Real-time syncing of orders, fees, and refunds * Automatic creation of accounting vouchers per transaction * Deep integration with ERP systems and ecommerce platforms This service requires a subscription with a provider such as [eMonkey](https://emonkey.no) or [Aritma](https://www.aritma.com). Contact the provider to set up the integration. > [!NOTE] > > Not sure which option fits your business? [Contact Dintero support](https://www.dintero.com/contact) to find the right setup. # Crystallize Source: https://docs.dintero.com/docs/integrations/crystallize Integrate Dintero Checkout into a Crystallize storefront. Integrate Dintero Checkout into your Crystallize storefront to accept payments. ## Prerequisites Before you begin, create an account in [Dintero Backoffice](https://backoffice.dintero.com) and collect the following credentials. See [API client setup](/docs/checkout/checkout-client) to find the values. * Account ID * Client ID * Client Secret > [!WARNING] > > The Client Secret is only shown once when you create an API client. Save it somewhere secure immediately after creation. ## Implementation Crystallize does not have a managed plugin. You integrate Dintero Checkout directly into your storefront code. The [**Remix Run Furniture v2 boilerplate**](https://github.com/CrystallizeAPI/furniture-remix) is a reference implementation that demonstrates a complete Dintero integration, including: * [A payment form](https://github.com/CrystallizeAPI/furniture-remix/blob/main/application/src/ui/components/payments/dintero.tsx) that locks the cart on submission * [Server-to-server payment](https://github.com/CrystallizeAPI/furniture-remix/blob/main/application/src/use-cases/payments/dintero/initiatePayment.ts) session creation * Cart persistence before pushing orders to Crystallize * [Transaction status verification](https://github.com/CrystallizeAPI/furniture-remix/blob/main/application/src/use-cases/payments/dintero/receivePayment.ts) * Automated customer and order creation in Crystallize after a successful authorization The Crystallize **Node Service API** includes [two request handlers](https://crystallize.com/learn/open-source/sdks-and-libraries/node-service-api-request-handlers) specifically designed to accelerate Dintero integration. # Magento 2 / Adobe Commerce Source: https://docs.dintero.com/docs/integrations/magento Install the Dintero Checkout plugin for Magento 2 and Adobe Commerce stores. Magento 2 (Adobe Commerce) is an open-source e-commerce platform. Dintero offers a checkout plugin for Magento 2 and Adobe Commerce stores. ## Prerequisites * Magento Open Source version 2.3 or newer. * A Magento account. * A Dintero account. See [API client setup](/docs/checkout/checkout-client) to create your API keys. ## Install the plugin **1. Add the plugin to your Adobe Commerce Marketplace cart** Go to [commercemarketplace.adobe.com](https://commercemarketplace.adobe.com/dintero-hp.html) page for the Dintero plugin, add it to your cart, complete the order, and click **Install**. **2. Generate access keys** In the Marketplace, select **Create A New Access Key** and save both the public and private keys. **3. Sync with Component Manager** In your Magento admin, go to **System** > **Web Setup Wizard**, select **Component Manager**, and **Sign in to sync your Marketplace purchases**. Enter the access keys from the previous step. **4. Install the module** Find `Dintero/hp` in the module list, start the installation, and follow the on-screen prompts. > [!WARNING] > > Back up your Magento installation before installing or updating any plugin. Dintero is not responsible for issues that occur during installation. ## Configure the plugin In your Magento admin, go to **Stores** > **Configuration** > **Sales** > **Payment Methods** > **Dintero HP** and enter your Dintero credentials. See [API client setup](/docs/checkout/checkout-client) to find these values in Backoffice. | Field | Where to find it | | - | - | | Account ID | Backoffice > Settings > Account info | | Client ID | Backoffice > Settings > API Keys | | Client Secret | Saved when you created the API client | | Payment profile ID | Backoffice > Settings > Payment Profiles | # nopCommerce Source: https://docs.dintero.com/docs/integrations/nopcommerce Install Dintero Checkout in a nopCommerce store. nopCommerce is an open-source e-commerce platform built on ASP.NET Core. Dintero offers a checkout plugin for nopCommerce stores. ## Installation Installation and configuration of the Dintero nopCommerce plugin is handled by Dintero's certified partners. Contact one of the following for integration support: * [HK Bits](https://hkbits.no/) * [Digitroll](https://www.digitroll.no/) ## Source code The plugin source code is available on GitHub: [github.com/Dintero/Dintero.Checkout.nopCommerce](https://github.com/Dintero/Dintero.Checkout.nopCommerce) # Optimizely (EPiServer) Source: https://docs.dintero.com/docs/integrations/optimizely Install the Dintero Checkout module for Optimizely Commerce (EPiServer Commerce). Install the Dintero Checkout module for Optimizely Commerce, formerly known as EPiServer Commerce. ## Prerequisites * Optimizely Commerce (EPiServer Commerce) version 10.9 or later. * A Dintero account with API keys and a payment profile. See [API client setup](/docs/checkout/checkout-client). ## Install the module Add the `Dintero.Checkout.Episerver` library from the Optimizely NuGet repository. The source code and reference implementation are available at [github.com/Dintero/Dintero.Checkout.Episerver](https://github.com/Dintero/Dintero.Checkout.Episerver). ## Configure the integration **1. Create a configuration page layout** Build a page layout named `ConfigurePayment.ascx` to manage these credentials from [Dintero Backoffice](https://backoffice.dintero.com): * Account ID * Client ID * Client Secret * Profile ID **2. Check for conflicting meta fields** Verify that a meta field named `DinteroSessionId` does not already exist in your system. **3. Create a DinteroPage instance** In EPiServer CMS, create a new instance of the `DinteroPage` page type. **4. Configure redirect pages** Add the following properties to your start page: * `DinteroPaymentCancelPage`: the page users land on after a failed authorization. * `DinteroPaymentLandingPage`: the page users land on after a successful authorization. **5. Create the payment method** Create a new payment method named `Dintero` with `Dintero` as the payment system identifier. ## Custom post-processing (optional) Implement the `IPostProcessDinteroPayment` interface to add custom logic that runs after authorization, capture, or refund. ## Supported features * Capture and partial refunds at item level within the EPiServer admin. > [!NOTE] > > Changes made in Dintero Backoffice are not automatically synced to EPiServer order management. Always capture and refund through EPiServer to keep order state consistent. # Plugins and integrations Source: https://docs.dintero.com/docs/integrations/plugins Browse Dintero's official plugins and partner integrations for ecommerce platforms, point-of-sale systems, and CMS tools that connect with Dintero Checkout. Dintero provides official plugins and partner integrations for popular ecommerce platforms and point-of-sale systems. Use a plugin to add Dintero Checkout to your store without building a custom integration. ## Dintero Checkout ### eCommerce platforms | Platform | Documentation | | - | - | | WooCommerce | [View guide](/docs/integrations/woocommerce) | | Shopify | [View guide](/docs/integrations/shopify) | | Magento 2 / Adobe Commerce | [View guide](/docs/integrations/magento) | | Crystallize | [View guide](/docs/integrations/crystallize) | | Optimizely / EpiServer | [View guide](/docs/integrations/optimizely) | | nopCommerce | [View guide](/docs/integrations/nopcommerce) | ### Point of sale | System | Documentation | | - | - | | ExtendaRetail Silent Touch | [View guide](/docs/integrations/silent-touch) | | ExtendaGO (Wallmob) | [View guide](/docs/integrations/wallmob) | | Traze | Contact Dintero | | Fixit | Contact Dintero | | Linework | Contact Dintero | | Fifty Two | Contact Dintero | | Flow Retail | Contact Dintero | | Vision Point | Contact Dintero | # Shopify Source: https://docs.dintero.com/docs/integrations/shopify Install Dintero payment apps in your Shopify store. Shopify is a popular e-commerce platform for creating an online store and selling products. Dintero offers several Shopify apps that let you accept payments through cards, Klarna, Vipps, and Swish. ## Prerequisites * A Shopify store. * A Dintero account and payment profile. See [API client setup](/docs/checkout/checkout-client). ## Recommended setup For most merchants, we recommend this setup: 1. Install the **Dintero Companion** app. 2. Install one or more payment method apps: * Cards * Klarna * Vipps (Norway) * Swish (Sweden) > [!TIP] > > Install the Companion app alongside your payment method apps, especially if you use Klarna, Walley, or Billie. These methods rely on detailed order line information for authorization, capture, and refunds. ## Available apps ### Dintero Companion The Companion app adds order line support for all other Dintero apps. It ensures that item details such as quantity, product name, VAT, and discounts pass correctly to Dintero. ![Shopify Companion app](https://mintcdn.com/dintero-c3a7bfec/5SNT3w02xCre3YZI/docs/assets/shopify/companion-app.png?fit=max\&auto=format\&n=5SNT3w02xCre3YZI\&q=85\&s=da12e4de24d317286b6810c2836d8023) > [card] [Install Dintero Companion](https://apps.shopify.com/dintero-companion) > > Adds order line support for all Dintero payment apps. ### Payment method apps Install a separate app for each payment method you want to offer. > [card] [Cards](https://apps.shopify.com/dintero-checkout-cards) > > Accept Visa and Mastercard payments through Dintero. > [card] [Klarna](https://apps.shopify.com/dintero-checkout-klarna) > > Offer Klarna Pay Now, Pay Later, and Financing in your checkout. > [card] [Vipps](https://apps.shopify.com/dintero-checkout-vipps) > > Add Vipps mobile payments. Available for Norwegian customers only. > [card] [Swish](https://apps.shopify.com/dintero-checkout-swish) > > Add Swish mobile payments. Available for Swedish customers only. > [card] [MobilePay](https://apps.shopify.com/dintero-checkout-mobilepay) > > Add MobilePay mobile payments. Available for Danish and Finnish customers only. > [card] [Billie](https://apps.shopify.com/dintero-checkout-billie) > > Offer Billie buy now, pay later for business (B2B) customers. ### Dintero Checkout unified app (not recommended) This app combines all payment methods into a single option at checkout. When customers select it, they are redirected to Dintero's secure payment page at `checkout.dintero.com`. > [!WARNING] > > We do not recommend the unified app for most merchants. Use a separate payment method app instead, unless you need one of the cases below. Use the unified app only if you need to: * Display a custom company logo or friendly name during payment. * Offer a single specific payment provider, such as Walley or Billie for B2B payments. If you use the unified app for a single payment provider: **1. Disable other methods in Dintero** In [Dintero Backoffice](https://backoffice.dintero.com), open your **Payment profile** and disable all other payment methods. **2. Activate one method in Shopify** Open the app settings in Shopify and make sure only the desired method is active. ## Common mistakes Review these common Shopify mistakes to avoid issues with refunds, captures, and disputes. > [accordion] Refunding an authorized order > > An order with status **Authorized** or **Processing** has not been captured yet. To release the customer's funds, cancel the order rather than issuing a refund. > [accordion] Expecting auto-capture > > Dintero does not auto-capture payments by default, in line with Nordic consumer protection laws. If you sell digital products and need auto-capture, contact Dintero support. > [accordion] Capturing or refunding in Dintero Backoffice > > Always capture and refund through Shopify. Performing these actions in Dintero Backoffice will not sync the changes back to Shopify, your order management system, or your warehouse system. > [accordion] Ignoring Klarna disputes > > You have 72 hours to respond to a Klarna dispute. Sign in to [portal.klarna.com](https://portal.klarna.com) with your Dintero account email address. Missing the deadline means automatically losing the case and the funds. > > See [handling disputes in the Klarna portal](/docs/integrations/support/klarna-disputes) for full instructions. # ExtendaRetail Silent Touch integration Source: https://docs.dintero.com/docs/integrations/silent-touch Use Dintero Checkout in store with ExtendaRetail Silent Touch 19.2 and later, including configuration steps and supported in-store payment flows. ExtendaRetail Silent Touch 19.2 and later supports Dintero Checkout for in-store payments. Customers pay via SMS link or, if only Vipps or Swish is enabled, a push notification sent directly to their app. **Demo videos (Norwegian):** * [Dintero Checkout via SMS](https://www.youtube.com/watch?v=fxblauREuDI) * [Vipps push notification](https://www.youtube.com/watch?v=IIs52xks9TU) ## Before you begin You need: * A Dintero account with production payment methods approved * An API client with Client ID and Client Secret * Your Account ID and Payment Profile ID See [API client setup](/docs/checkout/checkout-client) to create an API client and find your credentials. ## Step 1: Apply for payment methods In [Dintero Backoffice](https://backoffice.dintero.com), go to **Settings** > **Payment Connections** and apply for the payment methods you want to offer. ![Payment connections page in Dintero Backoffice](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/backoffice/apply_for_payment.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=479baa4618b45030420633d6cb2e9cb6) > [!NOTE] > > Approval typically takes 3 or more business days. Dintero notifies you by email when approved. ## Step 2: Create an API client 1. In Backoffice, go to **Settings** > **API Keys** > **Add new API keys**. 2. Click **Checkout Client**, enter a name, and click **Create API Client**. 3. Copy and save your **Client ID** and **Client Secret** immediately. The secret is only shown once. ## Step 3: Create a payment profile 1. In Backoffice, go to **Settings** > **Payment Profiles** > **New Payment profile**. 2. Enter a description and add your store logo URL. 3. Enable both: * **Automatically capture authorized transactions** * **Send the payment as push/SMS to the customer** 4. Click **Create payment profile** and copy the **Profile ID**. ![Create payment profile settings for in-store payments](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/backoffice/create_payment_profile_instore.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=3733e4a555923304dad47f81874c1884) ## Step 4: Configure Silent Touch In STConfig, go to **Functionality** > **Online payment** and set **OnlinePaymentType** to `Dintero`. Enter the following URLs: | Field | Value | | - | - | | Token URL | `https://api.dintero.com/v1` | | Checkout URL | `https://checkout.dintero.com/v1` | Then enter your credentials: | Field | Where to find it | | - | - | | Client ID | Backoffice > Settings > API Keys | | Client Secret | Saved when you created the API client | | Account ID | Your account ID with `P` prefix, for example `P12345678` | | Profile ID | Backoffice > Settings > Payment Profiles | ![Dintero settings in STConfig](https://mintcdn.com/dintero-c3a7bfec/D0VX9t09zInvinnk/docs/assets/silenttouch/dintero_settings.png?fit=max\&auto=format\&n=D0VX9t09zInvinnk\&q=85\&s=c77a9dc0bb343bc95ba1d7290a461422) ### Alternative: configure via STConfig.xml You can also set values directly in `STConfig.xml`: ```xml theme={null} Dintero your-client-id your-client-secret P12345678 P12345678.your-profile-id https://api.dintero.com/v1 https://checkout.dintero.com/v1 ``` Also enable "Online betaling" (712) under ``. ### Rename the payment button To change the label displayed at the till, create `ResourceOverrides.txt` in `C:\Program Files (x86)\SilentTouch\Mods`: ```txt theme={null} online|Vipps scoPaymentStepHeading|Dintero ``` ## Contact For help with setup, contact Dintero support: * Email: [support@dintero.com](mailto:support@dintero.com) * Phone: +47 22 34 34 54 # Add a user in Dintero Backoffice Source: https://docs.dintero.com/docs/integrations/support/add-user How to invite team members to your Dintero Backoffice account and set their access level. You can invite multiple users to your Dintero Backoffice account and control what each person can access. Users can process transactions, view reports, and send payment links. > [!NOTE] > > Sending payment links requires desktop access to Backoffice. ## Invite a team member **1. Open the Team settings** In [Dintero Backoffice](https://backoffice.dintero.com), go to **Settings** > **Team** and click **Add member**. ![Team page in Dintero Backoffice with Add member button highlighted](https://mintcdn.com/dintero-c3a7bfec/5SNT3w02xCre3YZI/docs/assets/support/add-user-step-1.jpg?fit=max\&auto=format\&n=5SNT3w02xCre3YZI\&q=85\&s=c3f61c4fd38fa8ec4017afc3085e7709) **2. Enter the email address** Type the new member's email address in the field. Press Enter to add it. You can add multiple addresses at once. ![Invite member form with email address field](https://mintcdn.com/dintero-c3a7bfec/5SNT3w02xCre3YZI/docs/assets/support/add-user-step-2.png?fit=max\&auto=format\&n=5SNT3w02xCre3YZI\&q=85\&s=f89211d944b65f24f2ccc137239887f2) **3. Set their access level** Select the roles and scopes for the new member. Each scope can be set to **Full** or **Read only**. ![Roles and access selection screen showing Full and Read only columns](https://mintcdn.com/dintero-c3a7bfec/5SNT3w02xCre3YZI/docs/assets/support/add-user-step-3.png?fit=max\&auto=format\&n=5SNT3w02xCre3YZI\&q=85\&s=1b97e9bdad2cc60d67011d560fc137e1) **4. Send the invitation** Click **Invite member**. The user receives an email invitation to join the account. ![Invite member confirmation button](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/add-user-step-4.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=982c40a428186f786f31eabf202191c7) # Auto-capture Source: https://docs.dintero.com/docs/integrations/support/auto-capture Understand how auto-capture works in Dintero, when it applies, and how it affects transaction fees. By default, Dintero authorizes payments but does not capture them automatically. You capture the payment manually when you are ready to dispatch the order. Auto-capture skips that manual step and captures the payment immediately after authorization. > [!NOTE] > > Some payment methods always capture immediately, regardless of this setting: [in-person payments](/docs/checkout/in-person/overview) and Swish. ## How capture works > [tab] Without auto-capture (default) > > 1. Customer pays. Dintero authorizes the amount and the order status becomes **Authorized**. > 2. You prepare and dispatch the order. > 3. You capture the payment in your platform or in Backoffice. The order status becomes **Captured** and funds are paid out. > > If the order is cancelled before capture, you cancel the authorization and no transaction fee is charged. > [tab] With auto-capture > > 1. Customer pays. Dintero authorizes and immediately captures the amount. The order status becomes **Captured**. > 2. Funds are paid out without any manual step. > > If the customer returns the order, you issue a refund. The transaction fee is not reversed. See [Transaction statuses](/docs/integrations/support/transaction-statuses) for a full overview of order states. ## Eligibility Consumer protection regulations prohibit capturing payment before dispatching to the customer. Auto-capture is only appropriate for businesses that fulfill orders at the point of sale or immediately after payment, such as: * Digital products (downloads, subscriptions, software licenses) * Restaurants and food service * Made-to-order or on-demand products > [!WARNING] > > Do not enable auto-capture if your business ships physical goods. You must not withdraw funds before dispatch. ## Effect on transaction fees | Capture method | When a fee is charged | Returns and cancellations | | - | - | - | | Manual (default) | Only when you capture | Cancel before capture: no fee. Partial capture: proportional fee. | | Auto-capture | On every completed payment | Fee is charged regardless of returns or refunds. | If your return or cancellation rate is high, the default manual capture can lower your total fee costs. ## Enable auto-capture Auto-capture is off by default. Contact [Dintero support](https://www.dintero.com/support) to enable it for your account. # Change your bank account number Source: https://docs.dintero.com/docs/integrations/support/change-bank-account How to update your bank account number for Dintero payouts. Bank account changes cannot be made in Backoffice. Contact Dintero support to update your payout account before your next payout. ## How to request a change Email [support@dintero.com](mailto:support@dintero.com) with the subject line **Bank account change: \[your account ID]** and include: * Your Dintero account ID * A photo or official bank statement showing the new account number Dintero will confirm when the account has been updated. Allow a few business days for processing. > [!WARNING] > > Submit your request well before your next scheduled payout. If a payout is sent to the old account before the change is processed, contact support immediately to arrange recovery. # Common order handling mistakes Source: https://docs.dintero.com/docs/integrations/support/common-mistakes Four mistakes to avoid when managing orders with Dintero Checkout, and what to do instead. These mistakes can result in stuck orders, customers charged incorrectly, or lost dispute cases. ## Refunding an authorized order An order with status **Authorized** (or **Processing**) has not been captured yet. Issuing a refund at this stage can leave the order stuck. > [!TIP] > > Cancel the order instead. This releases the reserved funds to the customer without creating a refund against a charge that never occurred. See [transaction statuses](/docs/integrations/support/transaction-statuses) for an overview of what each status means. ## Issuing a partial refund before capture If you need to remove items before shipping, do not issue a partial refund. The customer has not been charged yet, so there is nothing to refund. > [!TIP] > > Adjust the order lines and capture only the updated amount. The customer is then charged only for what you actually ship. See [capture orders](/docs/integrations/support/partial-capture) for how to do this. ## Completing transactions in Dintero Backoffice Processing a capture, void, or refund directly in Dintero Backoffice bypasses your webshop. These actions do not sync with your order management, TMS, or WMS systems, creating discrepancies between Dintero and your store. > [!TIP] > > Handle all transactions from within your ecommerce platform, such as WooCommerce. Changes made there propagate to Dintero automatically. ## Ignoring Klarna disputes When a customer files a dispute with Klarna, you receive an email notification. You have **72 hours** to respond. Missing the deadline means automatically losing the case and the funds. > [!TIP] > > See [handling disputes in the Klarna portal](/docs/integrations/support/klarna-disputes) for step-by-step instructions on how to respond. # Measure conversion rate in WooCommerce Source: https://docs.dintero.com/docs/integrations/support/conversion-rate-woocommerce How to track checkout conversion rate in WooCommerce using Google Analytics 4 or WooCommerce's built-in reports, and how your checkout configuration affects what you can measure. Conversion rate is the percentage of store visitors who complete a purchase: ```text theme={null} (Orders ÷ Unique visitors) × 100 ``` Tracking it helps you identify where customers drop off and measure the impact of changes to your checkout. ## Tracking methods ### Google Analytics 4 (recommended) GA4 gives you full funnel visibility. Install the official WooCommerce GA4 plugin and configure it to track these events: | Event | When it fires | | - | - | | `begin_checkout` | Customer starts checkout | | `add_payment_info` | Customer enters payment details | | `purchase` | Order is completed | With these events in place, you can see exactly where customers abandon the checkout flow. ### WooCommerce built-in analytics WooCommerce's built-in dashboard shows orders, revenue, and basic conversion data, but it does not give visibility into checkout funnel drop-offs. It is better suited to overall sales reporting than to optimizing checkout. ## How your checkout configuration affects tracking The way Dintero Checkout is configured in WooCommerce affects what you can measure: **Redirect checkout** creates a session only after the customer clicks the payment button. Customers who abandon before that point are not tracked. **Embedded checkout** creates a session as soon as the customer reaches the checkout page, giving you complete visibility into all touchpoints including early drop-offs. If conversion rate measurement is a priority, embedded checkout gives you more complete data. # Duration of authorizations Source: https://docs.dintero.com/docs/integrations/support/duration-of-authorizations How long Dintero holds an authorization for each payment method before it expires. When a customer pays, Dintero creates an authorization that reserves the amount at their bank. You must capture the payment before the authorization expires, or the customer will need to pay again. ## Quick reference | Payment method | Authorization window | | - | - | | Klarna | 28 days (auto-extended to 6 months) | | Walley | 90 days | | Card | \~7 days (up to 30+ days depending on bank) | | Vipps (Visa) | 7 days | | Vipps (Visa Electron) | 5 days | | Vipps (Mastercard) | 30 days | | Swish | No authorization, captured immediately | | In-person payments (Card (Present)) | No authorization, captured immediately | > [!WARNING] > > If an authorization expires before you capture, the customer must pay again. Use a [payment link](/docs/integrations/support/send-payment-link) to recover the order. ## Klarna You have **28 days** to capture. Dintero automatically extends the authorization after 23 days, up to a maximum of 6 months, so orders do not expire without warning. > [!NOTE] > > Auto-extension does not apply when the customer selects **Pay by card** within Klarna checkout. Klarna sends email notifications before each authorization period expires. The customer's invoice is only generated when you capture, not at authorization. For **installment** orders, the full authorized amount shows as Klarna debt until you capture or cancel. For **partial captures**, the remaining authorized amount receives a fresh 28-day window. You can extend it manually before expiry, up to 6 months in total. ## Walley You have **90 days** to capture Walley transactions (invoice and installments). The customer's invoice is generated when you capture. ## Card payments Card authorizations are typically valid for around **7 days**, but this varies by the customer's bank. Most cards allow captures beyond 30 days as long as the card remains valid and funded. ## Vipps The authorization window depends on the card type linked to the customer's Vipps account: | Card type | Authorization valid for | | - | - | | Visa | 7 days | | Visa Electron | 5 days | | Mastercard | 30 days | The customer's bank may release the reservation earlier than these limits. Capture is guaranteed within these windows if funds are available. ## Swish Swish skips the authorization stage entirely. Approved payments go directly to **Captured**, so there is no authorization window to manage. # Find your end-of-month balance Source: https://docs.dintero.com/docs/integrations/support/end-of-month-balance How to export transactions from Dintero Backoffice to calculate your balance at the end of a given month. To find your balance at the end of a given month, export the transactions that were both captured in that month and paid out. Summing those transactions gives you the closing balance. > [!NOTE] > > This only works for months where **all** transactions have already been paid out. If any captures from the target month are still pending payout, the export will not reflect the full balance. ## Export the transactions The logic is: captured in month X, paid out in month X+1. You apply both filters together so the export contains only settled transactions from your target month. **Example:** To find the balance for October, filter by capture date in October and payout date in November. **1. Filter by capture date** In Backoffice, go to **Payments** > **Transactions**. Click **More**, select **Capture date**, and set the date range to cover the entire target month. Apply the filter. **2. Add a payout date filter** Click **More** again, select **Payout date**, and set the date range to the month immediately after your target month. This limits the results to transactions that have been paid out. With both filters applied, you see only the transactions captured in your target month that have a payout date in the following month. **3. Export as CSV** Click **Export**, select **CSV** format with **Custom** date range, and confirm. ## Calculate the balance Open the CSV in Excel or a similar tool and sum the transaction amount column. That total is your end-of-month balance. # Checkout Express vs. standard Source: https://docs.dintero.com/docs/integrations/support/express-non-express Understand the difference between Checkout Express and standard checkout, and when to use each. Dintero plugins support two checkout modes. The mode you choose affects how customer contact details are collected during checkout. ![Checkout Express vs. standard checkout comparison](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/express-non-express.jpeg?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=a55c64223c58ec051d76173f0c083ed8) ## Comparison | | Checkout Express | Standard checkout | | - | - | - | | Customer contact details | Auto-filled for returning customers | Entered manually each time | | B2B invoicing | Supported | Not supported | | Browser verification | Some browsers require email or SMS confirmation | Not applicable | | Best for | Most stores | Stores where another plugin must collect customer data | ## Checkout Express Checkout Express remembers returning customers and pre-fills their contact details, including name and address, without requiring them to type them again. > [!NOTE] > > Some browsers require the customer to verify their email address or confirm via SMS before details are pre-filled. **B2B invoicing requires Checkout Express.** If you want to offer invoice payment for companies, you must activate this mode. ## Standard checkout Standard checkout presents a regular form where customers enter their contact details manually on every purchase. Use this if: * Another plugin in your store needs to collect customer data independently. * Your workflow requires a separate contact data collection step. ## Which should you use? Use Checkout Express for most stores. It reduces friction for returning customers and is the only mode that supports B2B invoicing. If you are unsure which fits your setup, contact [Dintero support](https://www.dintero.com/contact). # Handle disputes in the Klarna portal Source: https://docs.dintero.com/docs/integrations/support/klarna-disputes How to respond to customer disputes in the Klarna portal, including required documentation and response deadlines. When a customer files a dispute with Klarna, you must respond through the [Klarna portal](https://portal.klarna.com). Log in with the email address associated with your Dintero account. > [!WARNING] > > You have **72 hours** to respond to a dispute. Missing the deadline means you automatically lose the case. Klarna charges a 150 NOK/SEK chargeback fee plus the full transaction amount for lost disputes. ## Dispute categories | Category | Description | | - | - | | Returns | Full or partial order return | | Goods not received | Customer claims the order did not arrive | | Faulty goods | Item is broken, missing parts, or significantly different from the description | | Incorrect invoice | Missing discount or inaccurate item details | | Unauthorized purchase | Customer claims they did not make the purchase | | High-risk order | Flagged by Klarna's fraud detection, not customer-initiated | ## Required documentation for "Goods not received" If the dispute type is **Goods not received**, Klarna requires the following: * Tracking URL * Shipping provider name * Screenshots that show: * Delivery date (YYYY-MM-DD) and status * Full recipient address matching the checkout information * Recipient's full name matching the checkout records * Last-mile carrier tracking ID (not required for contactless deliveries) # Capture orders Source: https://docs.dintero.com/docs/integrations/support/partial-capture How to capture payment for a full or partial order, in WooCommerce or directly in Dintero Backoffice. Capturing an order charges the customer and triggers payout. You can capture the full order at once or in parts as items ship. > [!WARNING] > > If you use WooCommerce, always capture through WooCommerce rather than Dintero Backoffice directly. Capturing in Backoffice bypasses WooCommerce and will not update the order status, inventory, or connected logistics systems. ## Full capture ### In WooCommerce Capture the full order by setting its status to **Completed**. **1. Open the order** Go to **WooCommerce** > **Orders** and open the order. The status should be **Processing** or **On hold**, meaning the payment is authorized and ready to capture. **2. Set to Completed** Change the order status to **Completed** and save. ![Setting a WooCommerce order status to Completed](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/woo-complete.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=09acdab4809621042b282a10f8e4e179) WooCommerce sends a full capture request to Dintero. The customer is charged and the order is marked complete. ### In Dintero Backoffice (backup) Use this only if you cannot complete the order through WooCommerce. Update the WooCommerce order status manually afterward. **1. Find the order** In [Dintero Backoffice](https://backoffice.dintero.com), go to **Payments** and search for the order number. ![Locating an order in Dintero Backoffice](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/dintero-complete.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=4f7b355eecf4180cf5435705b0b0676b) **2. Capture the payment** Click **Capture**, verify the amount, and confirm. **3. Update WooCommerce** Open the order in WooCommerce and manually set the status to **Completed**. ## Partial capture Partial capture lets you charge the customer for part of an order now and capture the rest later. This is useful when items ship at different times. The order moves to status `partially_captured` after the first capture. The remaining authorized amount stays reserved at the customer's bank. See [Duration of authorizations](/docs/integrations/support/duration-of-authorizations) for how long the reservation is held. ### In WooCommerce > [!WARNING] > > This process removes product lines from the WooCommerce order. Do this only if inventory is tracked separately, or after accounting for the removed lines. **1. Set the order to Pending payment** Open the order and change the status to **Pending payment**. This pauses automatic processing. **2. Remove the items not shipping yet** Delete the product lines you are not capturing in this shipment. The order total updates to reflect only the remaining lines. **3. Set the order to Completed** Change the status to **Completed** and save. WooCommerce triggers a capture through Dintero for the remaining lines only. ### Capture the remaining balance in Backoffice When the rest of the order is ready to ship, capture the reserved amount. **1. Find the order** In [Dintero Backoffice](https://backoffice.dintero.com), go to **Payments** and open the order. **2. Capture the remaining amount** Click **Capture**, select the product lines to charge, adjust amounts if needed, and confirm. ## Cancel remaining balance If you will not ship the rest of the order, release the reserved amount. It disappears automatically from the customer's bank after a short period. To release it immediately: 1. In Backoffice, go to **Payments** and open the order. 2. Click **Cancel** and confirm. > [!WARNING] > > Cancelling the remaining amount is not supported for card payments via Worldline (Gateway), including Vipps, Swish, Apple Pay, Google Pay, and MobilePay. For these methods the reservation expires on its own. See [Duration of authorizations](/docs/integrations/support/duration-of-authorizations) for expiry timelines. # Payout troubleshooting Source: https://docs.dintero.com/docs/integrations/support/payout-missing Diagnose why a payout has not arrived or why the amount is different from what you expected. ## No payout received Work through these causes before contacting support. They are ordered from most to least common. > [accordion] Transactions are not captured > > Payouts only include transactions with status **Captured**. Authorized orders are not paid out until you capture them. > > Check your orders in Backoffice under **Payments** and capture any still in **Authorized** status. See [Capture orders](/docs/integrations/support/partial-capture) for how to capture in WooCommerce or Backoffice. > [accordion] Refunds exceeded your sales for the period > > If refunds in a payout period are larger than new sales, your balance goes negative. Dintero postpones the next payout until future sales cover the deficit. > > Check your payout report in Backoffice to see if a negative balance has carried forward from a previous period. > [accordion] Transaction captured after the payout cutoff > > Transactions captured after Tuesday's cutoff are included in the following week's payout. See [When to expect payouts](/docs/integrations/support/when-to-expect-payouts) for the full schedule. > [accordion] Card payment buffer not reached > > Card payments have a minimum sales buffer of **NOK 5,000**. Payouts are not generated until captured card sales in a period exceed this threshold. Sales below the buffer carry forward to the next period. > [accordion] Bank account number not registered or recently changed > > If you changed your bank account without notifying Dintero, payouts may be going to the old account or be on hold. See [Change your bank account number](/docs/integrations/support/change-bank-account). > [accordion] Payout holding period as a new customer > > New accounts sometimes have a short holding period. You should have been informed at signup. If you suspect this applies, contact [Dintero support](https://www.dintero.com/contact). If none of the above explains the missing payout, contact [Dintero support](https://www.dintero.com/contact) with your account ID and the expected payout date. ## Payout is lower than expected Negative balances from **returns** or **customer disputes** are deducted from the current period's turnover before the payout is calculated. The payout can therefore be lower than the gross total shown in your periodic report. Detailed breakdowns of these deductions are available in Swedbank and Vipps payout reports. Walley reports may not clearly show negative balances carried over from prior periods. ## Payout does not match your bank statement If your Dintero payout report and bank statement show different amounts, the most common cause is returns or disputes that created a negative balance applied against the current payout. To reconcile: 1. Download the payout report from Backoffice under **Reports** > **Reports**. 2. Compare the net payout amount on the report against your bank statement. 3. Check the transaction list for negative-amount lines (returns or disputes). See [Reports for Dintero Checkout](/docs/integrations/support/reports-overview) for how to read payout reports. # Refunds Source: https://docs.dintero.com/docs/integrations/support/refunds How to refund orders in WooCommerce and Dintero Backoffice. You can refund orders directly through the Dintero plugin in WooCommerce. Backoffice provides a backup method if the plugin is unavailable. > [!NOTE] > > Only **captured** orders can be refunded. If an order has status **Processing** in WooCommerce (authorized but not yet captured), cancel it instead of refunding. Cancelling before capture avoids the transaction fee; refunding after capture does not. Refunds typically reach the customer within 1–3 business days. ## Refund in WooCommerce **1. Open the order** Go to **WooCommerce** > **Orders**, open the order, and click the **Refund** button at the bottom of the order. ![Refund button on a WooCommerce order](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/refund-woo-step-1.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=f5f6d7412f040c7e87f5c17a7d3fc060) **2. Enter the quantity to refund** For each product line to refund, set the **Qty** field. The refund total updates automatically. To refund a full line, set it to the full quantity ordered. ![Setting refund quantity on a product line](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/refund-woo-step-2.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=0030c5c94454e2e4d012594b5579c43a) **3. Refund shipping (optional)** To refund shipping costs, enter the amount in the shipping row. ![Entering a shipping refund amount](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/refund-woo-step-3.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=8cc0211709c2246b8f8b0158e3c5fba1) **4. Submit the refund** Click **Refund \[amount] through Dintero Checkout**. The button label shows the calculated amount. Dintero processes the refund and it will appear on the customer's account within 1–3 business days. ## Refund via Dintero Backoffice Use this method if you cannot refund through the WooCommerce plugin. After refunding in Backoffice, you must manually update the order status in WooCommerce. **1. Find the order** In [Dintero Backoffice](https://backoffice.dintero.com), go to **Payments** and locate the order. ![Payments view in Dintero Backoffice](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/refund-backoffice-step-1.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=1479931e70dd297c49f867974350b369) **2. Click Pay back** Open the order and click **Pay back**. ![Pay back button on a Backoffice order](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/refund-backoffice-step-2.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=c17675949ee1c388393573343040f0af) **3. Select lines and confirm** Mark the lines to refund, verify the total, and confirm. ![Refund line selection in Dintero Backoffice](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/refund-backoffice-step-3.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=c0ac808eb50c929694aab3842f383ca3) **4. Sync the status in WooCommerce** Return to WooCommerce, open the order, and click **Refund \[amount] manually** to update the order status. # Report setup for sellers (marketplaces) Source: https://docs.dintero.com/docs/integrations/support/report-setup-sellers How marketplace operators can configure automatic payout report forwarding to individual sellers and their accountants. If you operate a marketplace, you can configure Dintero to automatically forward payout reports to each seller and their accountants by email. > [!NOTE] > > This applies to future reports only. Reports already generated cannot be forwarded retroactively. For a standard single-merchant setup, see [Reports for Dintero Checkout](/docs/integrations/support/reports-overview) instead. ## Set up report forwarding for a seller **1. Open payout report emails** In [Dintero Backoffice](https://backoffice.dintero.com), go to **Settings** > **Payout report emails**. **2. Create a subscription** Click **Create report email subscription**. ![Create report email subscription form in Dintero Backoffice](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/report-setup-sellers.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=7aa9a7a8d415bb327e92a5a38a665017) **3. Select the seller** Choose the seller ID from the dropdown. This list contains all sellers connected to your marketplace account. **4. Add recipients and choose formats** Enter one or more email addresses to receive the reports. Select the report formats you want to send (for example, PDF, CSV, or both). **5. Save the subscription** Click **Create** in the confirmation popup to activate the subscription. Repeat for each seller that needs report forwarding. # Reports for Dintero Checkout Source: https://docs.dintero.com/docs/integrations/support/reports-overview Overview of payout reports, periodic reports, and how to connect them to your accounting system. Dintero provides two types of reports: **payout reports** and **periodic reports**. Both are available in [Dintero Backoffice](https://backoffice.dintero.com). ## Payout reports A payout report is generated for each transfer Dintero sends to your bank account. It shows: * Gross amount for the payout period * Transaction fees deducted * Net amount transferred * Each individual transaction included Returns on previously paid orders appear as negative amounts. Only captured transactions within the payout period are included. ![Payout reports list in Dintero Backoffice](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/reports-payout-1.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=0235761d1485fbd79d85436aff7402b9) ![Payout report transaction detail](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/reports-payout-2.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=0d3926480ff3ee0acff00e54078b1d6c) ## Periodic reports Periodic reports show all transactions completed during a chosen period, independent of when they were paid out. Monthly reports are configured automatically. Find them in Backoffice under **Reports** > **Reports**. ![Periodic reports list in Dintero Backoffice](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/reports-periodic-1.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=20eeaa7d5de39b0e89e7ee8ca3eaeaf6) ![Periodic report detail view](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/reports-periodic-2.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=23c29141c8b0b00fb17530d562f251a3) To customize the schedule or format, go to **Settings** > **Report settings**: | Setting | Options | | - | - | | Period | Daily, weekly, or monthly | | Source | Transactions or open transactions | | Environment | Test or production | ## Connect to your accounting system You can have Dintero send payout reports automatically to your accounting software by email. **1. Find your accounting system's report email** In your accounting software, locate the unique email address for importing documents. This is specific to each application. **2. Add it in Backoffice** In [Dintero Backoffice](https://backoffice.dintero.com), go to **Settings** > **Account info** and click **Edit account**. Scroll to **Send payment report and invoice to** and enter the email address. ![Accounting system email field in Dintero Backoffice account settings](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/reports-accounting.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=fc10517a385cb72059609389dcbe37c7) For direct integrations with **PowerOffice Go**, **Tripletex**, **24SevenOffice**, and **Xledger**, use [eMonkey](https://www.emonkey.no/). If you operate a marketplace and need to forward reports to individual sellers, see [Report setup for sellers](/docs/integrations/support/report-setup-sellers). # Send a payment link Source: https://docs.dintero.com/docs/integrations/support/send-payment-link Send a payment link to a customer directly from Dintero Backoffice, without requiring them to visit your online store. A payment link lets you request payment from a customer outside of your online store. You create the link in Backoffice and send it by SMS, email, or a copied URL. ## When to use * Reissuing payment for a cancelled or refunded order * Recovering a failed checkout * Taking payment over the phone * Physical or door-to-door sales without a webshop ## Send a payment link [Create and Send a Payment Link to Customers](https://demo.arcade.software/jiE5y5iGbo1uT96xvItS?embed\&embed_mobile=tab\&embed_desktop=inline\&show_copy_link=true) **1. Open the payment link form** In [Dintero Backoffice](https://backoffice.dintero.com), click **Create** and select **Payment link**. **2. Choose payment methods** Select which payment methods to offer the customer. You can offer all available methods or restrict to specific ones. **3. Add order items** Add items with a description, quantity, and unit price. VAT defaults to 25% but you can adjust it per item. Prices cannot be zero. Use the trash icon to remove an item. **4. Configure the order** Set a reference or order number and choose a payment deadline: 1 day, 1 week, or 1 month. Decide whether to collect the customer's address, and whether to capture payment automatically when the customer pays or to authorize first and capture manually later. **5. Send the link** Choose a delivery method: | Method | How it works | | - | - | | SMS/Push | Sends an SMS. If Vipps is the only payment method, sends a Vipps push notification instead. | | Email | Opens your default email client with the payment link pre-filled. | | Link | Generates a URL you can copy and share however you like. | ## Track payment status After sending, you can follow the payment in real time. Backoffice shows when the customer opens the link and when payment is completed. Go to the **Payments** view in [Dintero Backoffice](https://backoffice.dintero.com) to check status. # Update technical email Source: https://docs.dintero.com/docs/integrations/support/technical-email How to update the technical email address that Dintero uses to send system notifications. Dintero sends system notifications to a designated technical email address. Notifications include alerts about integration issues and expiring API client authorizations. This is typically the email of the developer responsible for your Dintero integration, but it can be any email you choose. ## Update the address **1. Go to Settings** In [Dintero Backoffice](https://backoffice.dintero.com), select **Settings** from the left menu. ![Dintero Backoffice left navigation with Settings highlighted](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/terms-step-1.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=108e82640c514cb833231d8068d19391) **2. Open Business and click Business details** Go to **Business** under Account, go to the **Business details** tab. Click **Edit** on the top right of the Business details section. **3. Update the technical contact field** Find the **Technical contact** field and enter the new email. **4. Save** Click **Save**. # Add terms and conditions to checkout Source: https://docs.dintero.com/docs/integrations/support/terms-and-conditions How to display a link to your terms and conditions in the Dintero checkout. You can add a URL to your store's terms and conditions in Dintero Backoffice. Once set, the checkout displays a link to your terms for customers to review before paying. ## Add the URL **1. Go to Settings** In [Dintero Backoffice](https://backoffice.dintero.com), select **Settings** from the left menu. ![Dintero Backoffice left navigation with Settings highlighted](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/terms-step-1.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=108e82640c514cb833231d8068d19391) **2. Open Business and click Business details** Go to **Business** under Account, go to the **Business details** tab. **3. Enter your terms and conditions URL** Find the **Terms and conditions** section, click "Edit" on the top right of the section. Choose **Type of Terms** and enter your URL. ![Terms and conditions URL field in account settings](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/terms-step-3.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=2b89cbc3fb9f60228a4f69b109eb3b5f) **4. Save** Click **Save**. The checkout will now display a link to your terms. # Why transactions fail Source: https://docs.dintero.com/docs/integrations/support/transaction-failures Common reasons why Dintero payments fail and how to diagnose them. Payment failures can happen for several reasons. Understanding the cause helps you resolve the issue or guide customers through it. ## Common causes **Verification not completed** Customers must complete a security step like BankID or 3D Secure. Skipping or failing that step declines the payment. **Card issues** An expired card, insufficient funds, or a block placed by the customer's bank prevents the transaction. **Unsupported card type** Dintero supports most Visa and Mastercard products, but some international or business cards may be rejected. **Browser closed too early** Closing the browser before the redirect back to the store completes, which is common with Vipps or Swish, can prevent order confirmation even if the payment itself succeeded. **Temporary provider outage** Payment providers occasionally experience short outages. These typically resolve automatically. **Multiple checkout tabs** Opening checkout in multiple browser tabs at the same time can disrupt payment processing. ## Payment method-specific issues ### Digital wallets Apple Pay, Google Pay, Vipps, Swish, and MobilePay can fail due to: * An expired card linked to the wallet * A temporary outage at the provider * An incorrect phone number linked to the wallet account ### Buy now, pay later Klarna, Billie, and Walley may decline payments if: * The customer does not pass the provider's credit check * Your merchant agreement with the provider is inactive ## What to do if you're unsure Note the error message, payment method used, and the transaction or session ID. Contact [Dintero support](https://support.dintero.com) with these details so they can diagnose the failure. # Transaction statuses Source: https://docs.dintero.com/docs/integrations/support/transaction-statuses Understand what each Dintero transaction status means and which actions are available at each stage. Dintero transactions move through a fixed set of statuses from the moment a customer initiates payment. Use this page as a reference for what each status means and what you can do next. ## Status flow ![Dintero transaction status state diagram](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/checkout/transactionDiagramBig.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=8bfbd9493d614324c990138fc8d43bb6) ## Status reference | Status | API value | Description | Available actions | | - | - | - | - | | Initialized | `initialized` | Customer initiated payment | None | | On hold | `on_hold` | Held for manual review (Walley only) | None | | Authorized | `authorized` | Payment approved, funds not yet captured | Capture, partial capture, cancel | | Partially captured | `partially_captured` | Part of the authorized amount captured | Capture remaining, partial capture, partial refund, cancel remaining | | Partially captured, partially refunded | `partially_captured_refunded` | Part captured and part refunded on the same order | Refund, capture remaining | | Captured | `captured` | Full authorized amount captured | Refund, partial refund | | Cancelled | `authorization_voided` | Authorization voided, cannot be reversed | None | | Partially refunded | `partially_refunded` | Part of the paid amount refunded (1–3 business days) | Refund, partial refund | | Refunded | `refunded` | Full amount refunded to the customer (1–3 business days) | None | | Declined | `declined` | Customer actively declined the payment (e.g., dismissed a Vipps push) | None | | Failed | `failed` | Payment failed for technical reasons; customer must retry | None | | Unknown | `unknown` | Payment outcome could not be determined | None | ## WooCommerce status mapping | Dintero status | WooCommerce status | | - | - | | Initialized | Awaiting payment | | On hold | Manual review | | Authorized | Processing | | Partially captured | Completed | | Partially captured, partially refunded | Completed | | Captured | Completed | | Cancelled | Cancelled | | Partially refunded | Completed | | Refunded | Refunded | | Declined | Cancelled | | Failed | Cancelled | | Unknown | Cancelled | ## Common mistakes > [accordion] Refunding an authorized order > > An order with status **Authorized** has not been captured yet. Cancel it instead. The customer has not been charged, so there is nothing to refund. > [accordion] Issuing a partial refund before capture > > If you need to remove items before capture, adjust the order lines and capture only the updated amount. The customer is then charged only for what you ship. > > See [Capture orders](/docs/integrations/support/partial-capture) for how to do this in WooCommerce. See [Common order handling mistakes](/docs/integrations/support/common-mistakes) for more. # Update your logo in Dintero and Klarna Source: https://docs.dintero.com/docs/integrations/support/update-logo How to add or update your business logo in Dintero Checkout and in the Klarna payment flow. Your logo appears in the Dintero checkout and in the Klarna payment flow. Keeping it up to date gives customers a consistent, recognizable experience. Both platforms require a publicly accessible URL for your logo rather than a direct file upload. Use a PNG with a transparent background for best results. ## Update your logo in Dintero **1. Go to Settings** In [Dintero Backoffice](https://backoffice.dintero.com), select **Settings** from the left menu. **2. Open Account info and click Edit account** Go to **Account info** and click **Edit account** in the upper right. **3. Enter your logo URL** Enter the URL to your logo in the **Logo URL (optional)** field. You can also add an icon URL in the **Icon URL (optional)** field. **4. Save** Click **Save changes**. ## Update your logo in Klarna **1. Log in to the Klarna portal** Go to [portal.klarna.com](https://portal.klarna.com) and sign in with the email address associated with your Dintero account. **2. Open Brand manager** Navigate to **Payments** > **Home**, then scroll to find **Brand manager** under Preferences. **3. Upload your logo** Click **Upload** to add your logo. You can also update your display name here. **4. Save** Click **Save** in the upper right. # When to expect payouts Source: https://docs.dintero.com/docs/integrations/support/when-to-expect-payouts Understand Dintero's payout schedules and how long it takes to receive funds after a transaction is captured. Payouts are based on when transactions are **captured**, not when customers place their orders. An authorized order that you capture later is included in the payout period when the capture happens. ![Illustration of weekly payout schedule and processing timeline](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/payout-schedule.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=c2352eb14fc6ffbe34527983b4aeacaf) ## Processing time Due to processing time and AML (anti-money laundering) procedures, it takes **at least 2 business days** from when Dintero receives funds from the customer's bank or invoice partners before a payout can be generated. ## Payout schedules | Schedule | Payout day | Cost | | - | - | - | | Weekly (default) | Every Tuesday | Free | | Monthly | First Tuesday of the month | Free | | Daily | Every business day | 395 kr/month | For weekly and monthly schedules, transactions captured after Tuesday's cutoff are included in the next payout, not the current one. > [!TIP] > > Use the [payout date calculator](https://www.dintero.com/payouts) to find the exact date a specific transaction will be paid out. ## Enable daily payouts Daily payouts cost **395 kr/month** and apply only to domestic transactions in the same currency as your bank account. Cross-border transactions (for example, EUR payments to a NOK account) follow the standard weekly schedule regardless of this setting. **1. Open Additional services** In [Dintero Backoffice](https://backoffice.dintero.com), go to **Settings** > **Payments** > **Additional services**. ![Additional services settings in Dintero Backoffice](https://mintcdn.com/dintero-c3a7bfec/ADcpsKo9Wt_JnotC/docs/assets/support/daily-payouts-settings.png?fit=max\&auto=format\&n=ADcpsKo9Wt_JnotC\&q=85\&s=95217b7c346e031b9bf56026af701568) **2. Enable daily payouts** Toggle on **Daily payouts** and save. ## Payout not arrived? See [Payout troubleshooting](/docs/integrations/support/payout-missing). # Receipts and invoices in WooCommerce Source: https://docs.dintero.com/docs/integrations/support/woocommerce-create-receipts How to generate legally valid receipts and invoices for WooCommerce orders paid through Dintero. Dintero Checkout provides a payment confirmation comparable to a card terminal receipt. It is not a legally binding tax invoice. WooCommerce, as the point of sale, is responsible for generating itemized invoices that comply with local tax law. ## What a legal invoice must include * A unique, sequential, non-editable invoice number * Seller details: company name, address, and VAT or organization number * Customer billing address * Tax breakdown: net price, VAT percentage, VAT amount, and total * Transaction date or delivery date > [!NOTE] > > Tax requirements vary by country. Check with an accountant for the rules in your market. ## Recommended plugins > [card] [PDF Invoices & Packing Slips](https://wordpress.org/plugins/woocommerce-pdf-invoices-packing-slips/) > > The most widely used option. Automated PDFs with sequential numbering and customizable templates. Free. > [card] [WooCommerce PDF Invoices (Premium)](https://wpovernight.com/downloads/woocommerce-pdf-invoices-packing-slips-premium/) > > Adds credit notes, proforma invoices, and multi-currency layout support. > [card] [Germanized for WooCommerce](https://wordpress.org/plugins/woocommerce-germanized/) > > Built for strict compliance markets such as Germany, Norway, and the EU. > [!TIP] > > Start with **PDF Invoices & Packing Slips** if you are unsure which to use. It covers the legal requirements for most markets and is free to install. # ExtendaGO (Wallmob) integration Source: https://docs.dintero.com/docs/integrations/wallmob Enable Dintero Checkout inside ExtendaGO, the point-of-sale system formerly known as Wallmob, for in-store payments at retail and hospitality merchants. ExtendaGO (formerly Wallmob) is a point-of-sale system for retail and hospitality. You can enable Dintero Checkout to let customers pay by SMS link directly from the till. ## Before you begin You need a Dintero payment profile with **Send payment link via SMS/Push to customer** enabled. See [API client setup](/docs/checkout/checkout-client) to create your credentials. ## Setup guide Full setup instructions are provided by ExtendaGO: [ExtendaGO Dintero setup guide](https://www.extendago.com/wp-content/uploads/sites/3/2024/02/setup-dintero.pdf). ## Credential reference When following the setup guide, you will be asked for these values from [Dintero Backoffice](https://backoffice.dintero.com): | Field | Where to find it | | - | - | | Account identifier | Your account ID (digits only, no prefix) | | Client identifier | Backoffice > Settings > API Keys | | Client secret | Saved when you created the API client | | Payment profile identifier | Backoffice > Settings > Payment Profiles (includes `P` prefix) | ![Dintero credential fields in ExtendaGO settings](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/extendago/dintero_settings.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=d6c687bcbe63e38e08ab94e0d493db8a) # WooCommerce Source: https://docs.dintero.com/docs/integrations/woocommerce Install the Dintero Checkout WordPress plugin for WooCommerce stores. WooCommerce is a popular open-source e-commerce plugin for WordPress. Dintero offers a checkout plugin for WooCommerce stores. ## Prerequisites * A WordPress site with WooCommerce installed. * A Dintero account. See [API client setup](/docs/checkout/checkout-client) to create your API keys. ## Installation **1. Install the plugin** In your WordPress admin, go to **Plugins** > **Add new**, search for **Dintero**, then click **Install Now** and **Activate**. ![Step 1: install WooCommerce plugin](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/WooCommerce/step_1-woo-plugin.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=807b0ed4498e8bf6de9884c73171ccf6) **2. Connect your Dintero account** 1. Go to **WooCommerce** > **Settings** > **Payments**. 2. Click **Enable** on the Dintero plugin, then click **Manage**. 3. Open [Dintero Backoffice](https://backoffice.dintero.com) in another tab and create your [API client](/docs/checkout/checkout-client). 4. Paste the API keys into their respective fields in the plugin settings. ![Step 2: connect Dintero account](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/WooCommerce/step_2-woo-plugin.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=5bb44175cba606240ff695033e63bf3e) **3. Select a checkout flow** In the plugin settings, select your preferred checkout flow. **Checkout Express Embedded** is the recommended option. If you use an embedded option, adjust the layout settings to match your theme. [See the different checkout modes in action.](https://www.dintero.com/checkout-layouts) ![Step 3: select checkout flow](https://mintcdn.com/dintero-c3a7bfec/5SNT3w02xCre3YZI/docs/assets/WooCommerce/step_3-woo-plugin.png?fit=max\&auto=format\&n=5SNT3w02xCre3YZI\&q=85\&s=16d00874666cf2bc1058d04853849b8a) **4. Configure WooCommerce settings** 1. In WordPress, go to **WooCommerce** > **Settings** > **General** and set **Number of decimals** to `2`. 2. Turn off tax rounding: go to **WooCommerce** > **Settings** > **Tax** and make sure **Round tax at subtotal level** is off. ![WooCommerce tax rounding setting](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/WooCommerce/tax-rounding.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=cf4228539f87f9dc4649e030d23bf86e) ## Open firewall for Dintero traffic If your server uses a firewall, allow inbound traffic from the following Dintero IP addresses: * `34.241.230.119` * `34.242.13.162` See [Validating callbacks](/docs/checkout/validating-callbacks) for more information. ## Troubleshooting ### Orders stuck on hold An order can get stuck on **On hold** if the order amount or items in WooCommerce differ from what Dintero received. To force the order to the correct status: ![WooCommerce order stuck on hold](https://mintcdn.com/dintero-c3a7bfec/5SNT3w02xCre3YZI/docs/assets/WooCommerce/on-hold-woo.jpg?fit=max\&auto=format\&n=5SNT3w02xCre3YZI\&q=85\&s=2f218d3b29c0accd5231004e0f47c5b2) **1. Open two tabs** Open one tab with your plugin overview at `[your-domain.com]/wp-admin/plugins.php` and one with the order in WooCommerce. **2. Disable the Dintero plugin** In the plugins tab, deactivate the Dintero plugin. **3. Update the order status** In the order tab, set the order to the desired status. **4. Re-enable the plugin** Return to the plugins tab and activate the Dintero plugin again. > [!WARNING] > > Check the order in Dintero Backoffice after changing the status. The amount captured in Dintero is the amount you will receive, minus transaction fees. ### Reconnect an order number with a Dintero transaction ID If an order has lost its link to its Dintero transaction, you can reconnect them manually: 1. Open the order in the WooCommerce order edit page. 2. Edit the **Billing address** section and set **Dintero Checkout** as the payment method. 3. Paste the Dintero transaction ID into the **Transaction ID** field. ![WooCommerce: reconnect order to Dintero transaction](https://mintcdn.com/dintero-c3a7bfec/5SNT3w02xCre3YZI/docs/assets/WooCommerce/woo-order-connect-fix.png?fit=max\&auto=format\&n=5SNT3w02xCre3YZI\&q=85\&s=26c51c6711422ba14dd52a4c593f74c6) ## Advanced ### Apple Pay domain verification When using an embedded checkout on your own domain, Apple requires you to verify domain ownership before Apple Pay can be displayed to customers. See [Embedding the checkout on your own domain](/docs/checkout/apple-pay/apple-pay-hosted-checkout#embedding-the-checkout-on-your-own-domain) for the verification steps. ### Hide decimals in prices The plugin requires **Number of decimals** set to `2` in WooCommerce (see step 4 of installation). If you want to display prices without decimals in your store, add the following filter to your theme's `functions.php`: ```php theme={null} add_filter( 'woocommerce_price_trim_zeros', '__return_true' ); ``` This trims trailing zeros from displayed prices without changing the underlying decimal precision that Dintero requires. # Authentication Service Source: https://docs.dintero.com/docs/loyalty/auth-service Add login, account creation, and single sign-on for end users to your apps using the Dintero authentication service, scopes, and access tokens. ## Introduction to the Authentication service Our simple authentication service let your customers/end-users create account and use the same account to login to your multiple applications as MyPage, Loyalty apps, Online store etc. ## Add login to your single-page app ### How it works In a single-page application (SPA): 1. The user enters email/password in a login form hosted on the SPA and POST the details to the [login] resource. 2. API responds with the user's access token. ### Configure a login client A client with scope `accounts:auth:users` is required to access the [login] resource. Additional scopes must be added to grant access to user specific resources. | scope | description | | - | - | | `accounts:auth:users` | grant access to login and creating new user | | `customer_customers:read` | grant `read-only` to user | | `customer_customers:write` | grant `write-only` to user | | `customer_discounts:read` | grant `read-only` to user discounts | | `customer_receipts:read` | grant `read-only` to user receipts | | `create:accounts:auth:refresh_token` | enable issuing `refresh_token` | > **Note**: A login client with required grants can be created in [Backoffice][backoffice]. ### Login user with email/password In the SPA, use the "login client" to get an [access token]. The access token is required as authentication when accessing the [login] resource. ```curl theme={null} curl -X POST https://{server}/v1/accounts/{aid}/auth/token \ -H 'Content-Type: application/json' \ -u client_id:client_secret \ -d '{"grant_type":"client_credentials", "audience":"{audience}" }' ``` where `audience` is the audience that was used when creating the login client. Use the access token when requesting [login] of a user: ```curl theme={null} curl -X POST https://{server}/v1/accounts/{aid}/customers/login \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {client_access_token} \ -d '{"email":"", "password": "", "type": "", "audience":"{audience}"}' ``` A user access token will be returned on success. > **Note**: The user `password` must be set when [creating the user]. ### Reset password Reset of user password is done in three steps 1. Request [change password], the user will receive a verification code via email. 2. Login the user by verification code: ```curl theme={null} curl -X POST https://{server}/v1/accounts/{aid}/auth/token -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {client_access_token} \ -d '{"grant_type":"authorization_code", "audience":"{audience}", "verification_code: "" }' ``` 3. Update the user with [change password]. ## Refresh token A Refresh Token allows the application to ask Account-Auth service to issue a new Access Token without having to re-authenticate the user. This will work as long as the Refresh Token has not been revoked. > **Note** A Single-Page Application should not ever receive a Refresh Token, > this information is sensitive and should not be exposed client-side in a browser. ### Get a refresh token To get a Refresh Token, you must use a client with a grant that includes the * `create:account:auth:refresh_token` scope when requesting for a token. ```curl theme={null} curl -X POST https://{server}/v1/accounts/{aid}/customers/login \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {client_with_refresh_scope_access_token} \ -d '{"email":"", "password": "", "type": "", "audience":"{audience}"}' ``` The response should contain an Access Token and a Refresh Token ```json theme={null} { "access_token": "eyJhbGci...t7P4", "refresh_token": "eyGmkde...t3M3", "token_type": "Bearer", "expires_in": 86400 } ``` > **Note**: Refresh Token must be stored securely by an application since they > allow a user to remain authenticated essentially forever ### Use a refresh token To exchange the Refresh Token you received during authorization for a new Access Token, make a `POST` request to the `/accounts/{oid}/auth/token` endpoint using `grant_type=refresh_token`. ```curl theme={null} curl -X POST https://{server}/v1/accounts/{aid}/auth/token \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {client_with_refresh_scope_access_token} \ -d '{"grant_type":"refresh_token","refresh_token":"eyGmkde...t3M3"}' ``` The response include a new Access Token, its type, its lifetime (in seconds) ```json theme={null} { "access_token": "eyJhbGci...t7P4", "token_type": "Bearer", "expires_in": 86400 } ``` > You should only ask for a new token if the Access Token has expired. For > example, it's a bad practice to call the endpoint to get a new Access Token > every time you call an API. ### Revoke a refresh token Since Refresh Token never expire, it is essential to be able to revoke them in case they get compromised. You can [revoke a refresh token] by making a `POST` request to the `/accounts/{oid}/auth/token` endpoint using `token=REFRESH_TOKEN_TO_REVOKE` ```curl theme={null} curl -X POST https://{server}/v1/accounts/{aid}/auth/token \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {client_with_refresh_scope_access_token} \ -d '{"token":"eyGmkde...t3M3"}' ``` ## Add Vipps Login ### How it works In a single-page application (SPA): 1. The SPA creates a login link to login with Vipps 2. The user opens the login link and completes the login in the Vipps App 3. The SPA handles the redirect from Vipps and request access token via the API ### Configure grant for the login client Login with Vipps requires a client grant with `oidc` configured ```json theme={null} { "client_id": "{client_id}", "audience": "{audience}", "type": "authorization_code", "scope": [ "user:customers", "user:customers:/users?type=customer&phone_number" ], "oidc": { "authority": "https://api.vipps.no/access-management-1.0/access/.well-known/openid-configuration", "client_id": "{vipps-client-id}", "client_secret": "{vipps-client-secret}" } } ``` > [!NOTE] > > You can continue to support existing login with email or phone number by > including the grant scopes: > > * **`user:customers:/users?type=customer&phone_number`** > * **`user:customers:/users?type=customer&email`** > > The Vipps user will then be matched with existing user by matching the email or > phone number provided by Vipps > > User consent is required when matching email or phone number \[Vipps documentation] ### Create Vipps Login URL Use the [authorize with OIDC][authorize with OIDC] endpoint to create a Vipps Login URL ```text theme={null} GET: /auth/oidc/authorize?client_id={client_id} \ &response_type=code&scope={scopes}&state={state} \ &redirect_uri={redirect_uri} ``` **Query parameter examples** | query parameters | example | | - | - | | audience | `{dintero-grant-audience}` | | response_type | code | | client_id | `{dintero-client-id}` | | state | `{spa-generated-state}` | | redirect_uri | `{vipps-redirect-uri}` | | scope | `{vipps-scopes}` | > See [Vipps documentation] for supported query > parameters ### Get user token from Vipps login After a successful authentication, the user agent is redirected to the `{vipps-redirect-uri}` with the following parameters added to the query | query parameters | example | | - | - | | code | Authorization code generated by Vipps | | state | The exact value received from the client during authorization | Use the [token verified by OIDC] endpoint to get the user token ```json theme={null} { "grant_type": "authorization_code", "code": "{code}", "client_id": "{dintero-client-id}", "redirect_uri": "{vipps-redirect-uri}", "audience": "{dintero-grant-audience}" } ``` The response will look like this: ```json theme={null} { "access_token": "eyJhbGci...t7P4", "token_type": "Bearer", "expires_in": 86400, "user_info": { "authority": "https://identityserver.example.com/access", "value": { "sub": "c06c4afe-d9e1-4c5d-939a-177d752a0944", "name": "Ada Lovelace" } } } ``` [authorize with OIDC]: /management-auth-api/authenticate/aid_auths_oidc_authorize_get [token verified by OIDC]: /management-auth-api/authenticate/aid_auths_oidc_token_post [Vipps documentation]: https://github.com/vippsas/vipps-login-api/blob/master/vipps-login-api.md#oauth-20-authorize [creating the user]: /api-reference/users/aid_customers_post [access token]: /management-auth-api/authenticate/aid_auths_oauth_token_post [revoke a refresh token]: /management-auth-api/authenticate/aid_auths_oauth_revoke_post [change password]: /api-reference/password/aid_customers_change_password [login]: /api-reference/password/aid_customers_login_post [sign up]: https://onboarding.dintero.com/ [backoffice]: https://backoffice.dintero.com/ # API clients and application access Source: https://docs.dintero.com/docs/loyalty/clients Create and manage Dintero API clients with the right scopes so your helpdesk, ecommerce, point-of-sale, and back-office apps can access only the data they need. ## Create new applications / client for accessing your data When creating new applications/client that will use the API endpoints, the application needs to have the right access or scopes. If your Helpdesk application needs just access the customer data, the Helpdesk application needs access to `Customer Collection` & `Customer details` requests. Login to [Dintero Backoffice] for creating New Client in * `Settings` → `API Clients` → `Create New API Client` To create a client for checkout, see [Checkout API client]. You can also set up new API clients via our API. See [create a new client](/api-reference/clients/aid_auth_clients_post) and [grant scopes to the client](/api-reference/grants/aid_auths_client_grants_post) in the API reference. ## Available scopes | Name | Description | | - | - | | **`admin:account`** | Fully manage account and account user | |   `write:accounts` | | |   `read:accounts` | | |   `write:accounts:/auth/users` | | |   `write:accounts:/auth/passwordless` | | |   `write:accounts:/auth/passwordless/code` | | |   `write:accounts:/management/settings/connections/instabank` | | |   `write:accounts:/management/settings/connections/vipps` | | |   `create:account` | | |   `create:applicant` | | |   `create:accounts:auth:refresh_token` | | |   | | | **`admin:automations`** | Fully manage Automations | |   `write:automations` | | |   `read:automations` | | |   | | | **`admin:checkout`** | Fully manage checkout | |   `write:checkout` | | |   `read:checkout` | | |   | | | **`admin:customers`** | Fully manage eCRM Customer Data Platform | |   `write:customers` | | |   `read:customers` | | |   `create:customers:/users` |   | |   `public:customers` | Access public resources (read-only) | |   `user:customers` | | |   | | | **`admin:discounts`** | Fully manage DealEngine | |   `write:discounts` | | |   `read:discounts` | | |   `write:discounts:/available_for_receipt` | | |   `read:discounts:/available_for_receipt` | | |   `write:discounts:/events` | | |   `public:discounts` | Access public resources (read-only) | |   `user:discounts` | | |   | | | **`admin:hooks`** | Fully manage subscription hooks | |   `write:hooks` | | |   `read:hooks` | | |   | | | **`admin:locations`** | Fully manage sale locations | |   `write:locations` | | |   `read:locations` | | |   | | | **`admin:receipts`** | Fully manage eReceipts | |   `write:receipts` | | |   `read:receipts` | | |   `user:receipts` | | |   | | | **`admin:shopping`** | Fully manage Shopping | |   `write:shopping` | | |   `read:shopping` | | |   `write:shopping:/orders/ANY/events` | | |   `read:shopping:/orders/ANY/events` | | |   `user:shopping` | | |   | | | **`admin:wallets`** | Fully manage eWallet/eGift Cards | |   `write:wallets` | | |   `read:wallets` | | |   `write:wallets:/info` | | |   `write:wallets:/transactions` | | |   | | [Dintero Backoffice]: https://backoffice.dintero.com [Checkout API client]: /docs/checkout/checkout-client # Customer Service API Source: https://docs.dintero.com/docs/loyalty/customer-service Centralize customer profiles, identifiers, consents, and tags with the Dintero Customer Service so POS, ecommerce, and helpdesk apps share data in real time. ## Customer service introduction Customer service will help you store customer and user data and their consent in one centralized place, so all your applications can access the data in real-time like Point of Sale, eCommerce, Helpdesk, My Page, Loyalty programs etc. ## What can you do with Customer service? * Basics like creating customer objects, update customer objects etc. * Single sign on (SSO) and password management * Managing consents like newsletter consent, marketing consent, insight consent etc * Link multiple type of identification methods for your customers, like membership card, payment card (tokenized), phonenr, name,email etc. * Tagging customers * Attributes on customer object [Getting Started]: /docs/index [list of scopes]: #scopes [Terms of Service]: /api-reference/terms/aid_customers_terms_post # Discount and Reward Service Source: https://docs.dintero.com/docs/loyalty/discount-service Configure customer-specific discounts, coupons, stamp cards, and bonus rewards with the Dintero Discount and Reward Service across products and groups. ## Introduction - Discount & Reward service With Discount & Reward service, you can setup customer specific discounts and rewards. We support many type of rewards, like discounts,coupons, stamp/punch cards & bonus points: Type of discounts * % on product/productGroup/All products * Kr on product/productGroup/All products * Fixed price on product * Buy x and pay for y * Mix\&Match (If you buy Popcorn, Movie and Drink, get package deal of 150 NOK) Type of stamp and loyalty cards: * Buy x and get free product * Buy x and get discount on Y product Additional possibilities: * Max nr of usage: Customer can use the discount on 3 purchases * Max limit of number of product Customer can only use the discount on maximum 3 products * Selected of stores Discount can just be used in selected stores * Based on customer data Discount can just be used by customer with zipcode: 0400 * When Discount can only be used every Mondays from 10am to 11 am * Buy minimum for x amount to get discount ## Discount object The [discounts] object is structured like this: * discount information (name, links, picture ++) * requirements: can be items or items group, customer data, total amount, date from/to valid etc * reward: type of reward given. We support different type of rewards like amount, percentage, quantity etc. Look at the [API Reference] to see type of rewards in more detail * limitations: can be limit of how many discount that can be used on one purchase or on multiple purchases. > [!WARNING] > > NB! Discount service needs the Point of sale or eCommerce application to send the data needed to do the calculation of > discounts. For example if you have items or items group as requirement with an EAN, then POS or eCommerce need to send > the same EAN to discount service ## Create discounts (discount rules) from your campaign management application 1. [Create new discounts]. Look at the [discounts] examples codes to see multiple type of discounts. 2. [Add customers] to the discount created by sending `customer_ids`. If the discount is for all your customers, POST `*` instead of `customer_ids`. ## Apply & redeeming discounts for POS & eCommerce. ![Flow](https://mintcdn.com/dintero-c3a7bfec/TiCvqt4VXcXnNQNe/docs/assets/discountflow.png?fit=max\&auto=format\&n=TiCvqt4VXcXnNQNe\&q=85\&s=f790fad555896bc5a3dd389f18802846) 1. Customers need to identify themselves (Can use phonenr, membership card, payment cards etc instead of CustomerID.) 2. POS/eCommerce POST [shopping cart] to Dintero. 3. Discount service will return the shopping cart, where discount service will calculate the discount by adding discount lines on items level. (Discount service will also return discount rules applicable based on shopping cart, so POS/eCommerce can do local recalculations). 4. POS/eCommerce app needs to update the shopping cart with total amount and tax 5. Customers pays 6. POS/eCommerce claims discounts used by sending discountID & discount refs. 7. POS/eCommerce sends the final receipt by using [create new receipt] endpoint. This is optional. [discounts]: /api-reference/rules/aid_discounts_post [claims discounts]: /api-reference/use-discounts/aid_discounts_available_for_receipt_post_claim [create new receipt]: /api-reference/receipts/aid_receipts_post [create new discounts]: /api-reference/rules/aid_discounts_post [Add customers]: /api-reference/rules-customers/aid_discounts_did_customers_post [shopping cart]: /api-reference/use-discounts/aid_discounts_available_for_receipt_post [Create new receipt]: /docs/loyalty/receipt-service#sending-receipts-to-dintero-from-pos-ecommerce [API Reference]: /api-reference/rules/aid_discounts_post [support team]: mailto:support@dintero.com # Dintero API errors Source: https://docs.dintero.com/docs/loyalty/errors Reference for Dintero API error responses, including standard HTTP status codes and the detailed JSON error body, with examples for common failure scenarios. ## Errors We expose API errors in two ways: standard HTTP response code and a more detailed JSON format. For example, the following code snippet shows an HTTP 404 error in the response headers: ```http theme={null} HTTP/2 404 date: Sat, 11 Aug 2018 18:08:08 GMT content-type: application/json; charset=utf-8 content-length: 61 access-control-allow-origin: * access-control-allow-methods: GET,HEAD,PUT,PATCH,POST,DELETE access-control-allow-headers: Origin,Content-Type,Accept,Authorization,total-count,page-count etag: W/"3d-qtDvRirKA9JoksEsKn0JpUa7cpg" ``` And this snippet shows the error as JSON object: ```json theme={null} { "error": { "code": "NOT FOUND", "message": "Customer not found" } } ``` For HTTP response code, 4xx code suggest bad request. If you received a 4xx response, we recommend reviewing the [api-reference] for more context to help you troubleshoot. 5xx errors suggest a problem on Dintero's end. You’re welcome to contact our [support team] on any 5xx errors. If you contact support we recommend including the complete request you’re trying to make and the error code and response you’re receiving so they can help as quickly as possible. ## Downtime & status page Dintero API has a 99.99% uptime. We're rarely offline for planned maintenance, for example as part of major releases. We have a status page for our services. * [Status page] You can subscribe to incidents through the Status Page. ## Support To start, we recommend reviewing the [errors] section in this guide, and method-specific errors for the endpoint you're trying to access. If you're seeing a 5xx error, that likely means there's an error on Dintero side and you can contact our [support team]. [errors]: #errors [status page]: https://status.dintero.com [api-reference]: api-reference.md [support team]: mailto:support@dintero.com # Loyalty & Virtual Cards Source: https://docs.dintero.com/docs/loyalty/getting-started Connect your POS, ecommerce, and helpdesk apps to Dintero's Customer, Discount, Receipt, and Wallet services with a single API client. The Dintero Loyalty & Virtual Cards platform gives you four services that share a single API and authentication model: * **Customer service**: centralize customer profiles, identifiers, and consents across all your apps * **Discount & Reward service**: create and redeem coupons, loyalty cards, stamp cards, and bonus points * **Receipt service**: store digital receipts from all sales channels and stream data to your systems via webhooks * **Wallet service**: issue and accept virtual gift cards online and in-store ## Prerequisites * A Dintero account. Contact [support@dintero.com](mailto:support@dintero.com) if you don't have one. * Access to [Backoffice](https://backoffice.dintero.com/) to create API clients. ## Step 1: Create an API client Each application that accesses the API needs its own API client with the appropriate scopes. 1. Log in to [Backoffice](https://backoffice.dintero.com/). 2. Go to **Settings** → **API Clients** → **Create New API Client**. 3. Add the scopes your application needs. Grant only the scopes each application requires. A POS that redeems discounts does not need write access to customer profiles. | Service | Admin scope | Read scope | Write scope | | - | - | - | - | | Customer | `admin:customers` | `read:customers` | `write:customers` | | Discount | `admin:discounts` | `read:discounts` | `write:discounts` | | Receipt | `admin:receipts` | `read:receipts` | `write:receipts` | | Wallet | `admin:wallets` | `read:wallets` | `write:wallets` | See [API clients](/docs/loyalty/clients) for the full scope reference. ## Step 2: Authenticate Exchange your client credentials for a bearer token: ```bash theme={null} curl -X POST https://api.dintero.com/v1/accounts/T12345678/auth/token \ -u "CLIENT_ID:CLIENT_SECRET" \ -H "Content-Type: application/json" \ -d '{"grant_type": "client_credentials", "audience": "https://api.dintero.com/v1/accounts/T12345678"}' ``` The response includes an `access_token` (JWT) valid for 4 hours. Pass it as a bearer token on all subsequent requests: ```bash theme={null} Authorization: Bearer ``` Replace `T12345678` with your account ID. Use `T` prefix for sandbox, `P` prefix for production. See [Authentication service](/docs/loyalty/auth-service) for end-user login and single sign-on flows. ## Step 3: Choose your services > [card] [Customers & Users](/docs/loyalty/customer-service) > > Store customer profiles, link identifiers (phone, card token, membership number), and manage consents. > [card] [Discounts & Rewards](/docs/loyalty/discount-service) > > Configure loyalty programs, stamp cards, and coupons. Recalculate shopping carts before payment. > [card] [Receipts](/docs/loyalty/receipt-service) > > Send receipts from POS or ecommerce and expose purchase history to customers or downstream systems. > [card] [Gift Cards](/docs/loyalty/wallet-create-gift-card) > > Create virtual gift cards with a balance and accept them in Dintero Checkout or your own payment flow. # Receipt Service Source: https://docs.dintero.com/docs/loyalty/receipt-service Centralize digital receipts from all sales channels with the Dintero Receipt Service and stream the data to BI, data warehouse, or campaigns via webhooks. ## Introduction You can store all the receipt data from all channels in one place by sending the receipt to Dintero. You can also setup multiple subscribers of the receipt data by [Webhook service](/docs/checkout/webhooks) like Datawarehouse, BI, Campaign Planner etc. You can get receipts by: * CustomerID * ReceiptId Dintero can also offer digital receipts to customers instead of paper receipts. ## Sending receipts to Dintero from POS/eCommerce You create a new receipt / send receipt by one step. * [Create new receipt](/api-reference/receipts/aid_receipts_post) ## Showing receipts to customers 1. [Get a list](/api-reference/customer-receipts/aid_receipts_customers_cid_get) of receipts belong to customers. 2. [Get details](/api-reference/customer-receipts/aid_receipts_customers_cid_rid_get) of receipt. Will return the full json receipt. ### Minimum requirement for a valid receipt for accounting, expense reports etc. * Norway: [https://lovdata.no/dokument/LTI/forskrift/2015-12-18-1616](https://lovdata.no/dokument/LTI/forskrift/2015-12-18-1616) # Batch create gift cards Source: https://docs.dintero.com/docs/loyalty/wallet-batch-create-gift-card Pre-generate batches of physical Dintero gift cards with the wallet API so cards can be printed by your manufacturer and activated at point of sale. The Dintero wallet services support batch creation of gift cards. Use this when you need to pre-generate cards for printing before they are sold and activated. A typical example is a retail chain ordering a batch of physical gift cards from a card manufacturer. The cards are printed with the token and PIN, distributed to stores, and activated individually at the point of sale when a customer purchases one. ## Create a batch of gift cards Create 2 unactivated gift cards for printing ```http theme={null} POST https://api.dintero.com/v1/accounts/{aid}/wallets/cards/batch Authorization: Bearer Content-Type: application/json ``` ```json theme={null} { "cards": [ { "card_id": "card-01", "type": "gift_card" }, { "card_id": "card-02", "type": "gift_card" } ], "options": { "pin": { "format": { "length": 36, "prefix": "DINCARD:", "symbols": true, "numbers": true, "characters": true, "barcode": false } }, "card_token": { "format": { "length": 36, "prefix": "DINCARD:", "symbols": true, "numbers": true, "characters": true, "barcode": false } } } } ``` Cards created via batch are assigned status `inactive` and carry no balance. > [!NOTE] > > The `card_token` and `pin` for each card are included in the response and will > **not** be retrievable again after this call. Store or forward them immediately > for printing. > > * \[Wallets Batch API reference] ## Activate a gift card When a card is sold, activate it using: ```http theme={null} POST https://api.dintero.com/v1/accounts/{aid}/wallets/cards/{card_id}/activate Authorization: Bearer Content-Type: application/json ``` ```json theme={null} { "customer_id": "string", "name": "string", "amount": 50000, "currency": "NOK", "originated_by": "string", "active_from": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "metadata": { "dintero_transaction_id": "P12345678.xxxxx" } } ``` This transitions the card from `inactive` to `unused` and sets the balance. All fields are optional except amount and currency: | Field | Description | | - | - | | amount / currency  | Required. Initial balance loaded onto the card | | customer_id | Associate the card with a customer at point of sale | | active_from | Defaults to the time of activation if omitted | | expires_at | Omit if the card should not expire | | metadata | Recommended. Include the transaction that sold the card | > [!NOTE] > > Cards in `inactive` status cannot be used for payment. > > * \[Wallets Activate API reference] [Wallets Batch API reference]: /api-reference/cards/aid_cards_batch_post [Wallets Activate API reference]: /api-reference/cards/aid_cards_cardid_activate_post # Create a gift card Source: https://docs.dintero.com/docs/loyalty/wallet-create-gift-card Create gift cards with a balance using the Dintero wallet service and use them as a payment option in your own system, in Dintero Checkout, or in both. The Dintero wallet service can be used for creating gift cards with a balance. You can use the gift card as a payment option in your own payment solution, it can also be used in a Dintero Checkout session, or a combination of both. A typical example when you would use both is when you have physical stores in addition to an ecommerce site. The gift card can be sold in the physical store and used both there and in the Dintero Checkout on the ecommerce site. ## Create gift card Create a gift card of `500,- NOK`. ```http theme={null} POST https://api.dintero.com/v1/accounts/{aid}/wallets/cards Authorization: Bearer Content-Type: application/json { "card_id": "string", "customer_id": "string", "name": "string", "amount": 50000, "currency": "NOK", "pin": { "format": { "length": 4, "numbers": true } }, "card_token": { "format": { "length": 16, "numbers": true } } } ``` > [!NOTE] > > The `card_token` and `pin` that is included in the response when a card is > created must be shared with the customer. The example shows the recommended > minimum lengths. > > * \[Wallets API reference] ### Metadata > Use metadata to include additional information about the gift card We recommend that you use the metadata property to store information about the transaction/order that sold the gift card if available ```json theme={null} { "card_id": "string", ... "metadata": { "dintero_transaction_id": "P12345678.xxxxx" } } ``` ### Security We recommend that a separate API client is used when accessing the Wallets API. Access to create new gift card should be limited as the system that creates a session does not need to have access to the Wallets service You can create webhooks subscriptions to receive `wallet_transaction` events sent when new gift cards are created and used * [Webhooks API reference] [Wallets API reference]: /api-reference/cards/aid_cards_post [Webhooks API reference]: /webhooks-api/subscriptions/aid_source_hooks_post # Pay with a wallet gift card Source: https://docs.dintero.com/docs/loyalty/wallet-pay-with-gift-card Use a Dintero wallet gift card as a payment option in a standalone system: check balance, pay partially or fully, and collect the remainder by card or cash. A Wallet gift card can be used as payment option in a standalone payment system. For using with Dintero Checkout, see [Paying with Dintero Gift Cards in Checkout](/docs/checkout/gift-cards) The process is: 1. Check the balance of the gift card 2. Pay the order partially or fully with the funds available 3. Let payer pay the remaining amount with card/cash in the payment system. ### Check balance Use the info endpoint to get available funds that can be used in a sale transaction ```http theme={null} POST https://api.dintero.com/v1/accounts/{aid}/wallets/info Authorization: Bearer Content-Type: application/json { "token": "{card_token}" } ``` ### Create capture (sale transaction) > Use the `card_id` included in the info response ```http theme={null} POST https://api.dintero.com/v1/accounts/{aid}/wallets/transactions Authorization: Bearer Content-Type: application/json { "token": "{card_token}", "card_id": "string", "metadata": { "order_id": "xk39592f" }, "ref_id": "string", "amount": 50000, "currency": "NOK", "type": "drawdown", "pending": false } ``` > [!NOTE] > > See related API documentation for more information about balance and transaction > > * \[Wallets Info API reference] > * \[Wallets Transaction API reference] [Wallets Info API reference]: /api-reference/cards/aid_cards_token_post [Wallets Transaction API reference]: /api-reference/transactions/aid_cards_transactions_post # Model Context Protocol (MCP) Source: https://docs.dintero.com/docs/mcp Connect AI coding assistants like Claude, Cursor, and VS Code to the Dintero documentation using MCP. The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open standard that lets AI assistants search and read documentation directly. Your AI tools can look up API references, integration guides, and code examples without leaving your editor. ## Server URL The Dintero MCP server is available at: ```http theme={null} https://docs.dintero.com/mcp ``` ## Connect your AI tool > [tab] Claude Code > > Run this command in your terminal: > > ```bash theme={null} > claude mcp add --transport http dintero-docs https://docs.dintero.com/mcp > ``` > > Verify the connection > > ```bash theme={null} > claude /mcp > ``` > > The server is now available in all Claude Code sessions. Ask Claude to search the Dintero docs when you need API details or integration guidance. > [tab] Cursor > > **1. Open MCP settings** > > Open the command palette and select **Cursor Settings** > **MCP**. > > **2. Add the server** > > Click **Add new global MCP server** and add the following configuration: > > ```json theme={null} > { > "mcpServers": { > "dintero-docs": { > "url": "https://docs.dintero.com/mcp" > } > } > } > ``` > [tab] VS Code (Copilot) > > Create or update `.vscode/mcp.json` in your project: > > ```json theme={null} > { > "servers": { > "dintero-docs": { > "type": "http", > "url": "https://docs.dintero.com/mcp" > } > } > } > ``` > [tab] Claude (web) > > **1. Open connectors** > > Go to **Settings** > **Connectors** and click **Add connector**. > > **2. Configure the server** > > Set the name to **Dintero Docs** and the URL to `https://docs.dintero.com/mcp`. > > **3. Use it in a conversation** > > When composing a message, click the connector icon and select **Dintero Docs** to give Claude access to the documentation. ## Available tools The MCP server exposes three tools: | Tool | Description | | - | - | | **Search** | Full-text search across all documentation pages. Returns matching snippets with titles and links. | | **Query filesystem** | Read page content, browse the docs structure, and extract specific sections. Supports batch reads across multiple pages in a single call. | | **Submit feedback** | Report a problem with this documentation site so Dintero can fix it. Use when a documentation page is incorrect, outdated, confusing, incomplete, or has a broken example. | ## Example: Build a checkout integration With the MCP server connected, your AI assistant can guide you through a full integration by pulling details directly from the Dintero docs. Here's how a typical conversation might look: **1. Set up authentication** **Prompt:** "How do I authenticate with the Dintero API? Show me how to get an access token in Node.js." The assistant looks up the [auth service](/docs/checkout/quickstart#step-1-create-api-credentials) docs and returns working code using your account's OAuth 2.0 client credentials flow. **2. Create a checkout session** **Prompt:** "I need to start a payment for a 299 NOK order with one item. How do I set that up with the Dintero API?" The assistant reads the [session API reference](/docs/checkout/create-session) and generates a request with the correct endpoint, amount format (smallest currency unit), and required fields. **3. Display the checkout** **Prompt:** "How do I embed the Dintero checkout in my React app?" The assistant finds the [Web SDK](/docs/checkout/sdk/checkout-web-sdk) docs and shows you how to install `@dintero/checkout-web-sdk` and use the `embed` function with your session ID. **4. Handle the payment result** **Prompt:** "What happens after the customer pays? How do I verify the transaction?" The assistant pulls from [After payment](/docs/checkout/after-payment) to explain the callback and return URL flow, transaction statuses, and how to handle `ON_HOLD` scenarios. **5. Capture and refund** **Prompt:** "Show me how to capture this transaction, and how to do a partial refund later." The assistant reads the [transaction management](/docs/checkout/transaction-management) docs and returns the correct capture and refund endpoints with example payloads. > [!TIP] > > Be specific in your prompts. Instead of "help me with payments", try "show me the Dintero API request to capture a transaction for 150 NOK". The more context you give, the more accurate the response. ## More example prompts Beyond the checkout flow, try prompts like: * "How do I set up webhooks for transaction events in Dintero?" * "What test card numbers can I use in the Dintero sandbox?" * "Show me how to configure Express Checkout with shipping options" * "How does split payout work for marketplace sellers?" # Using Orders and Checkout together Source: https://docs.dintero.com/docs/order-management/checkout-orders Combine the Dintero Order Management and Checkout services to create draft orders, take payment, capture, and refund transactions in one flow. The Order Management and Checkout services are built to work together but can also be used independently. ## Authorization Create an [API client](/docs/checkout/checkout-client) with the following scopes: * `admin:checkout` * `admin:shopping` Note down the `client_id` and `client_secret` for use in the examples below. ## Steps **1. Create a draft order** Create a draft order with line items. The order is not yet active and can be freely modified. Orders API [POST /accounts/\{aid}/shopping/draft_orders](/api-reference/draft/aid_draft_orders_post) Example request body: ```json theme={null} { "options": { "generate_order_id": "ALPHANUMERIC_9" }, "order": { "currency": "NOK", "items": [ { "id": "175938", "line_id": 1, "quantity": 2, "gross_amount": 39800, "tax_lines": [{ "amount": 7960, "percentage": 25 }], "description": "Stablestol for utendørsbruk", "description_alias": "Stablestol" } ] } } ``` **2. Complete the draft order** Complete the draft to make the order active and assign it an `order_id`. Orders API [PUT /accounts/\{aid}/shopping/draft_orders/\{id}/complete](/api-reference/draft/aid_draft_orders_id_complete_put) **3. Create a checkout session** Create a checkout session, using the `order_id` as `merchant_reference`. Checkout API [POST /sessions-profile](/api-reference/session/checkout_session_profile_post) Example request body: ```json theme={null} { "url": { "return_url": "https://example.com/accept", "callback_url": "https://example.com/callback" }, "order": { "amount": 39800, "currency": "NOK", "merchant_reference": "order_id", "items": [ { "id": "175938", "line_id": "1", "description": "Stablestol for utendørsbruk", "quantity": 2, "amount": 39800, "vat_amount": 7960, "vat": 25 } ] }, "profile_id": "default" } ``` > [!NOTE] > > `profile_id` may vary. Check Backoffice for the correct value. Create the session: ```bash cURL theme={null} # Get access token curl 'https://api.dintero.com/v1/accounts/P12345678/auth/token' \ -H 'Content-Type: application/json' \ --user client_id:client_secret \ -d '{"audience": "https://api.dintero.com/v1/accounts/P12345678", "grant_type": "client_credentials"}' # Create session curl 'https://api.dintero.com/v1/accounts/P12345678/payments/sessions-profile' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer token' \ -d '' ``` ```python Python theme={null} from dintero import Dintero dintero = Dintero('T12345678', 'client_id', 'client_secret') checkout = dintero.checkout() session_info = checkout.create_session(session_body) ``` See [Display Checkout](/docs/checkout/display-checkout) for how to present the session to the customer. When payment completes, poll the transaction status and confirm it is `AUTHORIZED` before proceeding. **4. Mark the order as authorized** Record the authorization on the order to mark funds as reserved. Orders API [POST /accounts/\{aid}/shopping/orders/\{order_id}/authorizations](/api-reference/orderauthorizations/aid_orders_id_authorization_post) Example request body: ```json theme={null} { "items": [{ "amount": 39800, "line_id": 1 }], "payment_details": { "payment_id": "transaction_id" }, "success": true } ``` **5. Capture the transaction** Once items are ready to ship, capture the payment in the Checkout service. Then record the capture on the order to keep state in sync. Checkout API [POST /transactions/\{id}/capture](/api-reference/transactions/transactions_id_capture_post) Orders API [POST /accounts/\{aid}/shopping/orders/\{order_id}/captures](/api-reference/ordercaptures/aid_orders_id_capture_post) Example request body for the Orders API call: ```json theme={null} { "items": [{ "amount": 39800, "line_id": 1 }], "payment_details": { "payment_id": "transaction_id" }, "success": true } ``` **6. Refund the transaction** If the customer requests a refund, refund the payment in the Checkout service first. Then record the refund on the order. Checkout API [POST /transactions/\{id}/refund](/api-reference/transactions/transactions_id_refund_post) Orders API [POST /accounts/\{aid}/shopping/orders/\{order_id}/refunds](/api-reference/orderrefunds/aid_orders_id_refunds_post) Example request body for the Orders API call: ```json theme={null} { "items": [{ "amount": 39800, "line_id": 1 }], "payment_details": { "payment_id": "transaction_id" }, "success": true } ``` # Update an order with reversed items Source: https://docs.dintero.com/docs/order-management/order-update-refund Modify a Dintero order by reversing existing items and adding new ones using the draft order endpoints to keep the captured amount and refunds aligned. Update an order where existing items are reversed and new items are added. **1. Create the original order** Create a draft order with line items. [POST /accounts/\{aid}/shopping/draft_orders](/api-reference/draft/aid_draft_orders_post) Example request body: ```json theme={null} { "options": { "generate_order_id": "ALPHANUMERIC_9" }, "order": { "currency": "NOK", "items": [ { "id": "175938", "line_id": 1, "quantity": 2, "gross_amount": 39800, "tax_lines": [{ "amount": 7960, "percentage": 25 }], "description": "Stablestol for utendørsbruk", "description_alias": "Stablestol" } ] } } ``` Then complete it to make it active. [PUT /accounts/\{aid}/shopping/draft_orders/\{id}/complete](/api-reference/draft/aid_draft_orders_id_complete_put) **2. Authorize and capture the original order** Record the authorization and capture on the order to mark funds as reserved and collected. [POST /accounts/\{aid}/shopping/orders/\{order_id}/authorizations](/api-reference/orderauthorizations/aid_orders_id_authorization_post) [POST /accounts/\{aid}/shopping/orders/\{order_id}/captures](/api-reference/ordercaptures/aid_orders_id_capture_post) ```json theme={null} { "items": [{ "amount": 39800, "line_id": 1 }], "payment_details": { "payment_id": "PID_123" }, "success": true } ``` **3. Reverse the existing item and add a new one** Create a new draft linked to the original `order_id`. Include a reversal of the existing item (negative amounts) and a new replacement item. Use `related_item` to link the item being reversed. [POST /accounts/\{aid}/shopping/draft_orders](/api-reference/draft/aid_draft_orders_post) ```json theme={null} { "options": { "order_id": "{order_id}" }, "order": { "currency": "NOK", "items": [ { "id": "175938", "line_id": 2, "quantity": 2, "gross_amount": -39800, "tax_lines": [{ "amount": -7960, "percentage": 25 }], "description": "Stablestol for utendørsbruk", "description_alias": "Stablestol", "reversed_reason": "Replace item", "related_item": { "line_id": 1, "type": "reversed" } }, { "id": "003929", "line_id": 3, "quantity": 1, "gross_amount": 39800, "tax_lines": [{ "amount": 7960, "percentage": 25 }], "description": "Stablestol for innendørsbruk", "description_alias": "Stablestol Lux" } ] } } ``` Then complete the draft to apply the update to the order. [PUT /accounts/\{aid}/shopping/draft_orders/\{id}/complete](/api-reference/draft/aid_draft_orders_id_complete_put) **4. Authorize and capture the reversed and new items** Record the authorization and capture for both the reversed item (negative) and the new item. [POST /accounts/\{aid}/shopping/orders/\{order_id}/authorizations](/api-reference/orderauthorizations/aid_orders_id_authorization_post) [POST /accounts/\{aid}/shopping/orders/\{order_id}/captures](/api-reference/ordercaptures/aid_orders_id_capture_post) Reversed item: ```json theme={null} { "items": [{ "amount": -39800, "line_id": 2 }], "payment_details": { "payment_id": "PID_123" }, "success": true } ``` New item: ```json theme={null} { "items": [{ "amount": 39800, "line_id": 3 }], "payment_details": { "payment_id": "PID_123" }, "success": true } ``` **5. Refund remaining amount (if applicable)** If the original authorization is higher than the new items, include a refund line item in the draft update. Then authorize, capture, and refund that line. [POST /accounts/\{aid}/shopping/orders/\{order_id}/authorizations](/api-reference/orderauthorizations/aid_orders_id_authorization_post) [POST /accounts/\{aid}/shopping/orders/\{order_id}/captures](/api-reference/ordercaptures/aid_orders_id_capture_post) Authorize and capture the new item with the refund line: ```json theme={null} { "items": [ { "amount": 39800, "line_id": 3 }, { "amount": 1000, "line_id": 4 } ], "payment_details": { "payment_id": "PID_123" }, "success": true } ``` [POST /accounts/\{aid}/shopping/orders/\{order_id}/refunds](/api-reference/orderrefunds/aid_orders_id_refunds_post) Refund the remaining amount: ```json theme={null} { "items": [{ "amount": 1000, "line_id": 4 }], "payment_details": { "payment_id": "PID_123" }, "success": true } ``` **6. Additional captures for partial authorization (if applicable)** If the original authorization is lower than the new item amount, add additional authorization and capture calls for the new item. [POST /accounts/\{aid}/shopping/orders/\{order_id}/authorizations](/api-reference/orderauthorizations/aid_orders_id_authorization_post) [POST /accounts/\{aid}/shopping/orders/\{order_id}/captures](/api-reference/ordercaptures/aid_orders_id_capture_post) ```json theme={null} { "items": [{ "amount": 1000, "line_id": 3 }], "payment_details": { "payment_id": "PID_321" }, "success": true } ``` # Order Management Source: https://docs.dintero.com/docs/order-management/overview Create, track, and manage the full lifecycle of orders. From draft through payment, capture, and refund. ## What is Order Management? The Dintero Order Management API lets you create and manage orders independently of payment. Payment is handled by your payment system. The Order Management API records what has happened (authorized, captured, refunded) but does not execute payment operations itself. ## Order lifecycle **1. Draft** Create a draft order with line items. The order is not yet active and can be freely modified. [POST /accounts/\{aid}/shopping/draft_orders](/api-reference/draft/aid_draft_orders_post) **2. Active** Complete the draft to make the order active and assign it an `order_id`. [PUT /accounts/\{aid}/shopping/draft_orders/\{id}/complete](/api-reference/draft/aid_draft_orders_id_complete_put) **3. Authorized** Authorize the payment in your payment system. Then record the authorization on the order to mark funds as reserved. [POST /accounts/\{aid}/shopping/orders/\{order_id}/authorizations](/api-reference/orderauthorizations/aid_orders_id_authorization_post) **4. Captured** Capture the payment in your payment system. Then record the capture on the order to keep the order state in sync. [POST /accounts/\{aid}/shopping/orders/\{order_id}/captures](/api-reference/ordercaptures/aid_orders_id_capture_post) **5. Refunded or Cancelled** Refund the payment in your payment system and record the refund on the order, or cancel an uncaptured order. [POST /accounts/\{aid}/shopping/orders/\{order_id}/refunds](/api-reference/orderrefunds/aid_orders_id_refunds_post) [POST /accounts/\{aid}/shopping/orders/\{order_id}/cancel](/api-reference/orderstatus/aid_orders_id_cancel_post) ## Guides > [card] [Orders and Checkout](/docs/order-management/checkout-orders) > > How to combine the Order Management and Checkout services. Create a draft order, take payment, capture, and refund in one end-to-end flow. > [card] [Update an order (reversing)](/docs/order-management/order-update-refund) > > How to modify an existing order by reversing items and adding new ones, keeping captured amounts and refunds aligned. # Inviting merchants Source: https://docs.dintero.com/docs/partners/inviting-merchants Use the Dintero Partner API to invite merchants for onboarding so they can accept Dintero's terms of service and start accepting payments under your account. Merchants must complete onboarding themselves so they can accept Dintero's [terms of service](https://www.dintero.com/legal). There are two flows for creating new merchants under your partner account. Both accept an optional `signup_reference` parameter that you can use to track which invitation a merchant signed up from. You can retrieve this value later from the `applicant.signup_reference` field when you [get the account settings](/partners/account-settings/aid_account_aid_get). ## Alternative 1: Self-service onboarding You link the merchant to the Dintero onboarding form. The merchant submits their details, accepts the terms of service, verifies their email address, and creates a password for their Dintero account. ```text wrap theme={null} https://onboarding.dintero.com/?partner={partner_id}&signup_reference={signup_reference} ``` Example: `https://onboarding.dintero.com/?partner=112&signup_reference=abc-123` ## Alternative 2: Prefilled onboarding You prefill the merchant's details using the prefill form. The merchant receives an email with a link to review and edit their details, accept the terms of service, and create a password. ```text wrap theme={null} https://onboarding.dintero.com/prefill?partner={partner_id}&signup_reference={signup_reference} ``` Example: `https://onboarding.dintero.com/prefill?partner=112&signup_reference=abc-123` ## Requesting in-person payments for a new merchant Partners can request that in-person payments (IPP, using physical terminals) be enabled for a new merchant during the onboarding process. > [tab] Backoffice > > In [Backoffice](https://backoffice.dintero.com/), open **Partner admin** and click **Invite new merchant**. In the integration settings section of the new merchant form, check **Terminal payments** and submit the form. > > The IPP request is saved to the new merchant account and is reflected in the KYC process. > [tab] API > > When creating the merchant account with [`POST /accounts/{oid}/management/accounts`](/partners/accounts/aid_mgmnt_accounts_post), include `ipp` in `onboarding.requested_payment_methods`: > > ```json theme={null} > { > "onboarding": { > "requested_payment_methods": ["ipp"] > } > } > ``` > > See the [create account](/partners/accounts/aid_mgmnt_accounts_post) API reference for the full request schema. ## Get notified when merchants are onboarded Subscribe to the `account_add` and `account_update` webhook events to get notified when a merchant completes onboarding or updates their information. ```bash wrap Request theme={null} curl -X POST https://api.dintero.com/v1/accounts/T11200000/hooks/subscriptions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "config": { "url": "https://example.com/webhooks/dintero" }, "events": [ "account_add", "account_update" ] }' ``` See the [create webhook subscription API reference](/partners/subscriptions/aid_source_hooks_post) for all available options. # List merchant accounts Source: https://docs.dintero.com/docs/partners/list-merchants List the merchant accounts under your Dintero partner account using the management auth API and pagination so you can drive operations workflows or dashboards. ## Listing merchants Get a list of all merchant accounts under your partner account. ```bash Request theme={null} curl https://api.dintero.com/v1/accounts/T11200000/management/accounts \ -H "Authorization: Bearer " ``` ```json Response theme={null} [ { "account_id": "T11200001", "partner_id": "T112", "active": true, "livemode": false, "company": { "business_name": "Acme Store AS", "organization_number": "987654321", "website": "https://acme-store.example.com" }, "applicant": { "first_name": "Jane", "last_name": "Doe", "email": "jane@acme-store.example.com", "signup_reference": "abc-123" }, "paging_token": "pt1" } ] ``` ## Pagination The response returns up to 10 accounts by default. Use `limit` (1--100) and `starting_after` to paginate through results. Each account in the response includes a `paging_token` value that you pass as `starting_after` to fetch the next page. ```bash wrap Request theme={null} curl "https://api.dintero.com/v1/accounts/T11200000/management/accounts?limit=50&starting_after=pt1" \ -H "Authorization: Bearer " ``` ## Filtering You can filter accounts by payment connection, country, or service status using query parameters. ```bash wrap Request theme={null} curl "https://api.dintero.com/v1/accounts/T11200000/management/accounts?country=NO&services=checkout.status.enabled" \ -H "Authorization: Bearer " ``` See the [merchant account collection API reference](/partners/accounts/aid_mgmnt_accounts_get) for all available filters and response fields. # API clients and grants Source: https://docs.dintero.com/docs/partners/manage-merchants-via-api Create API clients and delegate grants on a merchant account using the Dintero Partner API. Include the merchant access token from the [merchant account API access](/docs/partners/partners-merchant-api-access) flow as the `Authorization` header in your requests. Creating an API client is a two-step process: create the client, then delegate grants to it. **1. Create the API client** See the [Create client API](/partners/clients/aid_auth_clients_post) for full reference. ```bash wrap Request theme={null} curl -X POST https://api.dintero.com/v1/accounts/T11200001/auth/clients \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "API client for e-commerce", "description": "Created by partner", "client_id": "ecom-123" }' ``` ```json wrap Response theme={null} { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "API client for e-commerce", "description": "Created by partner", "client_id": "ecom-123", "client_secret": "JYCRP/x7iBGWA1fun0J9laH5sEg5cP9g/4QivhfGzm4" } ``` **2. Create client grants** See the [Create client grant API](/partners/grants/aid_auths_client_grants_post) for full reference. Use the `id` from the previous step as the `client_id` value. ```bash wrap Request theme={null} curl -X POST https://api.dintero.com/v1/accounts/T11200001/auth/client-grants \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "client_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "audience": "https://api.dintero.com/v1/accounts/T11200001", "scope": [ "checkout:admin" ], "type": "client_credentials" }' ``` # Partners Source: https://docs.dintero.com/docs/partners/partners Introduction to the Dintero Partner API for inviting and managing merchants, covering how partner accounts work. As a Dintero partner, you get a dedicated partner account with API access to invite and manage merchants. You can automate merchant onboarding, configure payment settings, create API clients, and pull settlement and insight reports on behalf of your merchants. You also get access to a single partner [Backoffice](https://backoffice.dintero.com/) where you can manage all your merchants in one place. To become a Dintero partner, [apply on the partner page](https://www.dintero.com/partners) or contact [partners@dintero.com](mailto:partners@dintero.com). ## Partner account IDs Partner account IDs end with five zeros. For example, account ID `T11200000` has partner ID `112`. Merchant accounts created under your partner account are linked to this ID. Dintero account IDs are prefixed with `T` for sandbox accounts and `P` for production accounts. Use sandbox accounts during development and switch to production when you are ready to go live. ## Overview ```mermaid theme={null} flowchart TD A[Partner account] -->|Authenticate| B[Partner API] B -->|Invite| C[Merchant onboarding] C -->|Merchant accepts ToS| D[Merchant account] B -->|Exchange token| D D --> E[Payment profiles] D --> F[Reports] D --> G[API clients & grants] ``` **1. Get your partner account** After signing up, you receive a partner account with access to the Partner API and tracking links. **2. Create an API client** Create an API client in [Backoffice](https://backoffice.dintero.com/) and save your Client ID and Client Secret. Authenticate to get a bearer token. **3. Invite merchants** Use the self-service onboarding link or the prefilled onboarding form to invite merchants. Merchants accept Dintero's terms of service and set up their own password. **4. Manage merchant accounts** Exchange your partner token for a merchant access token to configure payment profiles, create API clients, and pull reports on behalf of your merchants. ## Merchant onboarding > [card] [Inviting merchants](/docs/partners/inviting-merchants) > > Invite merchants to onboard with Dintero under your partner account. > [card] [List merchant accounts](/docs/partners/list-merchants) > > List all merchant accounts under your partner account. > [card] [Merchant account API access](/docs/partners/partners-merchant-api-access) > > Get an access token to call APIs on behalf of a merchant. ## Merchant account management > [card] [API clients and grants](/docs/partners/manage-merchants-via-api) > > Create API clients and delegate grants for a merchant. > [card] [Payment profiles](/docs/partners/payment-profiles) > > Create, list, and update payment profiles for a merchant. > [card] [Reports](/docs/partners/reports) > > Access settlement reports and configure insight reports. # Access a merchant account Source: https://docs.dintero.com/docs/partners/partners-merchant-api-access Exchange a partner exchange token for a Dintero merchant access token so you can call APIs on behalf of one of your merchants under your partner account. To call the API on behalf of a merchant, you need to exchange your partner access token for a merchant access token. **1. Authenticate as a partner** Create an API client and use the credentials to [create an access token](/partners/authenticate/aid_auths_oauth_token_post). **2. Obtain an exchange token** Use the `access_token` from step 1 to request an [exchange token](/partners/authenticate/aid_auths_oauth_exchange_token_post). ```bash wrap Request theme={null} curl -X POST https://api.dintero.com/v1/accounts/T11200000/auth/exchange_token \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "account_id": "T11200001" }' ``` ```json Response theme={null} { "access_token": "eyJhbGci...t7P4", "token_type": "Bearer", "expires_in": 14400, "refresh_token": "..." } ``` **3. Exchange for a merchant access token** Use the `access_token` from step 2 to request a [merchant token](/partners/authenticate/aid_auths_oauth_token_post). ```bash wrap Request theme={null} curl -X POST https://api.dintero.com/v1/accounts/T11200001/auth/token \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "grant_type": "client_credentials", "audience": "https://api.dintero.com/v1/accounts/T11200000" }' ``` ```json Response theme={null} { "access_token": "eyJhbGci...d5F1", "token_type": "Bearer", "expires_in": 14400, "refresh_token": "..." } ``` **4. Verify access** Use the merchant access token to retrieve the account details. The response includes the optional `applicant.signup_reference` that was set during onboarding. ```bash wrap Request theme={null} curl https://api.dintero.com/v1/accounts/T11200001/management/settings \ -H "Authorization: Bearer " ``` ```json Response theme={null} { "account_id": "T11200001", "partner_id": "T112", "active": true, "livemode": false, "company": { "business_name": "Acme Store AS", "organization_number": "987654321", "website": "https://acme-store.example.com" }, "applicant": { "first_name": "Jane", "last_name": "Doe", "email": "jane@acme-store.example.com", "signup_reference": "abc-123" } } ``` See the [get account settings API reference](/partners/account-settings/aid_account_aid_get) for all response fields. # Payment profiles Source: https://docs.dintero.com/docs/partners/payment-profiles Create, list, and update payment profiles for your merchants using the Dintero Partner API. Payment profiles control which payment methods are available in a merchant's checkout session. As a partner, you can manage these profiles on behalf of your merchants using the merchant access token from the [merchant account API access](/docs/partners/partners-merchant-api-access) flow. ## Create a payment profile ```bash wrap Request theme={null} curl -X POST https://api.dintero.com/v1/admin/session/profiles \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "profile_id": "default", "description": "Default payment profile", "configuration": { "active_payment_types": { "enabled": true } } }' ``` See the [create payment profile API reference](/partners/profiles/admin_session_profile_post) for all available options. ## List payment profiles ```bash wrap Request theme={null} curl https://api.dintero.com/v1/admin/session/profiles \ -H "Authorization: Bearer " ``` See the [list payment profiles API reference](/partners/profiles/admin_session_profile_get) for response details. ## Update a payment profile ```bash wrap Request theme={null} curl -X PUT https://api.dintero.com/v1/admin/session/profiles/default \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "profile_id": "default", "description": "Default payment profile", "configuration": { "active_payment_types": { "enabled": true } } }' ``` See the [update payment profile API reference](/partners/profiles/admin_session_profile_details_put) for all available fields. # Reports Source: https://docs.dintero.com/docs/partners/reports Access settlement reports and configure insight reports for your merchants using the Dintero Partner API. A Dintero merchant can have two types of reports: settlement reports and insight reports. Use the merchant access token from the [merchant account API access](/docs/partners/partners-merchant-api-access) flow to access reports on behalf of your merchants. ## Settlement reports Settlement reports are created when settlements are paid out by the payment processors (Dintero Payout, Vipps, Swedbank Pay, Bambora, Walley, and Klarna). See [the payouts guide](https://www.dintero.com/payouts) for when to expect a settlement after a transaction is captured. ### List settlements Each item in the response can contain multiple attachments, including the source files from the payment processor and the normalized Dintero settlement reports. ```bash wrap Request theme={null} curl https://api.dintero.com/v1/accounts/T11200001/settlements \ -H "Authorization: Bearer " ``` See the [settlement reports API reference](/partners/settlements/aid_settlements_list) for filtering options and response details. ### Get notified about new settlements Subscribe to the `settlement_add` webhook event to get notified when a settlement is added. ```bash wrap Request theme={null} curl -X POST https://api.dintero.com/v1/accounts/T11200001/hooks/subscriptions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "config": { "url": "https://example.com/webhooks/dintero" }, "events": [ "settlement_add" ] }' ``` See the [create webhook subscription API reference](/partners/subscriptions/aid_source_hooks_post) for all available options. ## Insight reports Insight reports are created from transaction data and do not contain settlement information. They are generated automatically at scheduled intervals such as `weekly` or `monthly`. ### Create a report configuration ```bash wrap Request theme={null} curl -X POST https://api.dintero.com/v1/accounts/T11200001/insight/reports/configuration \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "dataType": "checkout/transactions", "schedule": "weekly", "language": "en" }' ``` See the [create insight report configuration API reference](/partners/report-configuration/aid_report_configuration_post) for all available options. ### List reports ```bash wrap Request theme={null} curl https://api.dintero.com/v1/accounts/T11200001/reports/metadata \ -H "Authorization: Bearer " ``` See the [list insight reports API reference](/partners/reports/api_reports_metadata_list_get) for response details. # Responsible disclosure policy Source: https://docs.dintero.com/docs/security/responsible-disclosure-policy How to report security vulnerabilities to Dintero under our responsible disclosure policy, including the reporting process, scope, and what to expect. Dintero greatly appreciates input from security researchers wanting to help. We encourage responsible vulnerability research and disclosure. If you discover a vulnerability in any of our systems, please let us know about it so we can address it as quickly as possible. ## Reporting a vulnerability If you have discovered an issue you want to report, please do the following: * Email your findings to [security@dintero.com](mailto:security@dintero.com). * Include details of what the issue is, how you discovered it, and attach any screenshots and such if possible. See the section below for additional details that are useful to include in the report. * Ensure you give enough details for us to reproduce the issue. * Please do not take advantage of the vulnerability you have found. * Please do not disclose the vulnerability to others until it is resolved. ## Vulnerability related information 1. Product or service in which the vulnerability is found. * Product or service name * Product or service URL 2. Anomalous behavior caused by the vulnerability. 3. Procedure for reproduction of the vulnerable condition. 4. Probability of the reproduction, choose one from the following three: * Always * Often * Rarely 5. Possible threat caused by the vulnerability. 6. Workaround. 7. PoC (Proof of Concept) code. 8. Other comments from the reporter (including severity assessment) * Describe the specific impact and how you would envision it being used in an attack scenario. * Do you believe the vulnerability is being exploited? Yes/No * Is an exploit publicly available? Yes/No ## Scope Any of Dintero services, products or web properties are **in scope**. The following issues are currently considered **out of scope**: * Volumetric/Denial of Service vulnerabilities (i.e. simply overwhelming our service with a high volume of requests). * Missing email best practices (invalid, incomplete or missing SPF/DKIM/DMARC records, etc.). * Self-XSS. * Social engineering and physical security attacks. * Brute force attacks. * SSL/TLS configuration weaknesses. * Clickjacking and other issues only exploitable through clickjacking. * CSV/formula injection. * Spoofing attacks. ## Phishing If you want to report suspicious emails that seems to be coming from Dintero, please forward it to [phishing@dintero.com](mailto:phishing@dintero.com). If you have any questions or comments about the reporting process please use our [Contact Form](https://www.dintero.com/contact-us). ## Bug bounty We currently do not offer a paid bug bounty program. ## Ground rules We will not take legal action against security researchers reporting their findings in a responsible manner to us or our Customer Service Center by following the instructions in this document. We ask you to: * Play by the rules and follow our Disclosure Policy. * Do not violate the privacy of others by e.g. sharing or not properly securing data. * Never attempt to gain access to another user’s account or data. * Promptly report any vulnerabilities you find to us as described in this document. * Do not disclose any vulnerabilities or associated details to anyone other than your dedicated Dintero security analyst. * Allow our security team reasonable time to resolve the issue. ## Feedback If you want to give feedback or suggestions to this policy, submit your feedback to [security+feedback@dintero.com](mailto:security+feedback@dintero.com). We are continually improving this policy and appreciate your input. # Get Account settings Source: https://docs.dintero.com/partners/account-settings/aid_account_aid_get /mintlify-docs/openapi/spec-management-auth.yaml get /accounts/{aid}/management/settings Get details about the account scopes: - admin:accounts - read:accounts # Update Account Settings Source: https://docs.dintero.com/partners/account-settings/aid_account_settings_put /mintlify-docs/openapi/spec-management-auth.yaml put /accounts/{aid}/management/settings Update account settings scopes: - admin:accounts - write:accounts # Get Account Source: https://docs.dintero.com/partners/accounts/aid_accounts_aid_get /mintlify-docs/openapi/spec-management-auth.yaml get /accounts/{oid}/management/accounts/{aid} Get account details scopes: - admin:accounts - read:accounts # Partner onboarding link Source: https://docs.dintero.com/partners/accounts/aid_accounts_aid_partner_onboarding_link_post /mintlify-docs/openapi/spec-management-auth.yaml post /accounts/{oid}/management/accounts/{aid}/partner_onboarding_link Partner onboarding link scopes: - admin:dintero - write:dintero:/management/accounts # Update Account Source: https://docs.dintero.com/partners/accounts/aid_accounts_aid_put /mintlify-docs/openapi/spec-management-auth.yaml put /accounts/{oid}/management/accounts/{aid} Update an account scopes: - admin:accounts - write:accounts - write:dintero:/management/accounts # Delete Account Source: https://docs.dintero.com/partners/accounts/aid_mgmnt_accounts_aid_delete /mintlify-docs/openapi/spec-management-auth.yaml delete /accounts/{oid}/management/accounts/{aid} Delete an account scopes: - admin:accounts - write:accounts # Accounts collection Source: https://docs.dintero.com/partners/accounts/aid_mgmnt_accounts_get /mintlify-docs/openapi/spec-management-auth.yaml get /accounts/{oid}/management/accounts Get list of accounts filtered by the partner account scopes: - admin:accounts - read:accounts # Create Account Source: https://docs.dintero.com/partners/accounts/aid_mgmnt_accounts_post /mintlify-docs/openapi/spec-management-auth.yaml post /accounts/{oid}/management/accounts Create an account from an partner account scopes: - admin:accounts - write:accounts - public:accounts In order to create an account with `livemode` correctly enabled, the following fields must be set in the body request: - `company.business_name` - `company.organization_number` - `company.address.address_line` - `company.address.postal_place` - `company.address.country` - `company.website` - `billing.business_name` - `billing.organization_number` - `billing.address.address_line` - `billing.address.postal_place` - `billing.address.country` This allows the account to proceed with KYC in Backoffice. # Exchange Token Source: https://docs.dintero.com/partners/authenticate/aid_auths_oauth_exchange_token_post /mintlify-docs/openapi/spec-management-auth.yaml post /accounts/{partner_id}/auth/exchange_token Use this endpoint to exchange access_token to a sub-account scopes: - admin:accounts - read:accounts # Get Token Source: https://docs.dintero.com/partners/authenticate/aid_auths_oauth_token_post /mintlify-docs/openapi/spec-management-auth.yaml post /accounts/{oid}/auth/token Use this endpoint to directly request an access_token ### Client Access Token Use HTTP Basic authentication scheme for authenticating grant_type `client_credentials`, use client_id/client_secret as user/password. ### Code/Password Token Use HTTP Bearer authentication scheme for authenticating grant_type `authorization_code` or `password`, where the Bearer value must be a JWT toke with access to the token endpoint. ### Account User Token Use HTTP Bearer authentication scheme for authenticating grant_type `account_user_token`, where the Bearer value must be a account user JWT token. > Use ID token as Bearer toke if the user was authenticated > externally. The ID must include a `email` claim that > identifies the account user. ### Refresh Token Use HTTP Bearer authentication scheme for authenticating grant_type `refresh_token` where the Bearer value **must** be an Access Token for the clients that was used to create the Refresh Token. ### Multi-factor authentication (MFA) When a request is made to the endpoint to get an access token, normally you either get an error, or you get an access token. However, when the MFA is enabled, the endpoint may return a new error with `error.code: mfa_required`. When an `mfa_required` error is returned, the client must perform a `challenge`. This is done by sending a request to the [auth/mfa/challenge](/management-auth-api/challenge/aid_auth_mfa_challenge_post) endpoint To verify MFA using an OOB challenge, the client must make a request to this endpoint with `grant_type=mfa-oob`. Include the `oob_code` you received from the challenge response, as well as the `mfa_token` you received as part of mfa_required error. scopes: - admin:accounts - write:accounts - write:accounts:/auth/users - write:accounts:/auth/users/no-mfa # Create Client Source: https://docs.dintero.com/partners/clients/aid_auth_clients_post /mintlify-docs/openapi/spec-management-auth.yaml post /accounts/{oid}/auth/clients Creates a new client application. scopes: - admin:accounts - write:accounts # Client grants collection Source: https://docs.dintero.com/partners/grants/aid_auths_client_grants_get /mintlify-docs/openapi/spec-management-auth.yaml get /accounts/{oid}/auth/client-grants Manage your Client Grants (also called Client Credentials Grants). Using Client Grants, your Client can request an access token using its credentials (a Client ID and a Client Secret). The access token then represents your Client during API calls. Use the Grant type to limit how the grant can be used when requesting an access token. A Grant with type `password` can only be used when requesting an access token with grant_type set to `password`. scopes: - admin:accounts - read:accounts # Delete client grant Source: https://docs.dintero.com/partners/grants/aid_auths_client_grants_id_delete /mintlify-docs/openapi/spec-management-auth.yaml delete /accounts/{oid}/auth/client-grants/{id} scopes: - admin:accounts - write:accounts # Create client grant Source: https://docs.dintero.com/partners/grants/aid_auths_client_grants_post /mintlify-docs/openapi/spec-management-auth.yaml post /accounts/{oid}/auth/client-grants scopes: - admin:accounts - write:accounts # Delete session profile Source: https://docs.dintero.com/partners/profiles/admin_session_profile_details_delete /mintlify-docs/openapi/spec-checkout.yaml delete /admin/session/profiles/{profile_id} scopes: - admin:checkout - write:checkout:/admin/session/profiles # Get session profile details Source: https://docs.dintero.com/partners/profiles/admin_session_profile_details_get /mintlify-docs/openapi/spec-checkout.yaml get /admin/session/profiles/{profile_id} scopes: - admin:checkout - write:checkout:/admin/session/profiles - read:checkout # Update session profile Source: https://docs.dintero.com/partners/profiles/admin_session_profile_details_put /mintlify-docs/openapi/spec-checkout.yaml put /admin/session/profiles/{profile_id} scopes: - admin:checkout - write:checkout:/admin/session/profiles # List profiles Source: https://docs.dintero.com/partners/profiles/admin_session_profile_get /mintlify-docs/openapi/spec-checkout.yaml get /admin/session/profiles scopes: - admin:checkout # Create session profile Source: https://docs.dintero.com/partners/profiles/admin_session_profile_post /mintlify-docs/openapi/spec-checkout.yaml post /admin/session/profiles scopes: - admin:checkout - write:checkout:/admin/session/profiles - read:checkout # Create new insight report configuration Source: https://docs.dintero.com/partners/report-configuration/aid_report_configuration_post /mintlify-docs/openapi/spec-insight.yaml post /accounts/{aid}/insight/reports/configuration Create a new report configuration scopes: - write:insight - admin:insight # Delete insight report configuration Source: https://docs.dintero.com/partners/report-configuration/aid_reports_configuration_delete /mintlify-docs/openapi/spec-insight.yaml delete /accounts/{aid}/insight/reports/configuration/{id} Delete insight report configuration. scopes: - write:insight - admin:insight # List insight configurations Source: https://docs.dintero.com/partners/report-configuration/aid_reports_configuration_get /mintlify-docs/openapi/spec-insight.yaml get /accounts/{aid}/insight/reports/configuration List all insight report configurations for the account. scopes: - read:insight - admin:insight # Update insight report configuration Source: https://docs.dintero.com/partners/report-configuration/aid_reports_configuration_put /mintlify-docs/openapi/spec-insight.yaml put /accounts/{aid}/insight/reports/configuration/{id} Update insight report configuration. Scopes: - write:insight - admin:insight # Generate report from data Source: https://docs.dintero.com/partners/reports/api_reports_generation_post /mintlify-docs/openapi/spec-reports.yaml post /accounts/{aid}/reports/generation Using this endpoint with the query parameter **save** set to true, will result in an **201** response, otherwise, the response will be **200**. #### Generate PDF report for transaction: First, fetch the transaction from [Get transaction](/api-reference/default/transactions_id_get). Store the transaction in the `transaction` variable and send this payload: [ { "key": "transaction", "path": "/checkout/v1/transactions/{transaction.id}", "data": transaction } ] with these query parameters set: - template_id=checkout_transaction_order - template_data_path=/checkout/v1/transactions/{transaction.id} - template_accept=application/pdf - template_accept_language=en **scopes**: - admin:reports - write:reports - read:reports # List report metadata Source: https://docs.dintero.com/partners/reports/api_reports_metadata_list_get /mintlify-docs/openapi/spec-reports.yaml get /accounts/{aid}/reports/metadata Get list of report metadata for the account Scopes: - read:reports - admin:reports # Generate a test settlement report Source: https://docs.dintero.com/partners/settlements/aid_settlement_generate_test_report /mintlify-docs/openapi/spec-billing.yaml post /accounts/{aid}/settlements/reports/generate-test-report Generate a test settlement report. Only available in test. *scopes*: - admin:billing - admin:reports # List settlements Source: https://docs.dintero.com/partners/settlements/aid_settlements_list /mintlify-docs/openapi/spec-billing.yaml get /accounts/{aid}/settlements List settlements *scopes*: - admin:billing - read:billing - admin:reports - read:reports - admin:settlements - read:settlements # Download attachment Source: https://docs.dintero.com/partners/settlements/settlement_attachment_download /mintlify-docs/openapi/spec-billing.yaml get /accounts/{aid}/settlements/{settlementid}/attachments/{attachmentid} Download a settlement attachment *scopes*: - admin:billing - read:billing - admin:reports - read:reports - admin:settlements - read:settlements # Get delivery details Source: https://docs.dintero.com/partners/subscription-deliveries/aid_source_hooks_hid_deliveries_did_get /mintlify-docs/openapi/spec-webhooks.yaml get /accounts/{aid}/hooks/subscriptions/{hid}/deliveries/{delivery_id} Get subscription delivery details scopes: - admin:hooks - read:hooks # List subscription deliveries Source: https://docs.dintero.com/partners/subscription-deliveries/aid_source_hooks_hid_deliveries_get /mintlify-docs/openapi/spec-webhooks.yaml get /accounts/{aid}/hooks/subscriptions/{hid}/deliveries Get recent subscription deliveries scopes: - admin:hooks - read:hooks # Subscription ping Source: https://docs.dintero.com/partners/subscription-deliveries/aid_source_hooks_hid_ping_post /mintlify-docs/openapi/spec-webhooks.yaml post /accounts/{aid}/hooks/subscriptions/{hid}/ping This will trigger a ping event to be sent to the subscription URL. ### Ping Event Payload ```http POST / User-Agent: Dintero-Hook/0c9ad03b Content-Type: application/json event: ping event-delivery: cfedde7e-b088-415e-ad5b-cbe54acbb6f9 { "created_at": "2017-12-06T15:36:43Z", "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e", "id": "string", "updated_at": "2017-12-06T15:36:43Z", "active": true, "config": { "content_type": "application/json", "insecure_ssl": 0, "secret": { ... } "url": "string" }, "events": ["receipt_add"] } ``` # List subscriptions Source: https://docs.dintero.com/partners/subscriptions/aid_source_hooks_get /mintlify-docs/openapi/spec-webhooks.yaml get /accounts/{aid}/hooks/subscriptions Get a list of all subscriptions scopes: - admin:hooks - read:hooks # Delete Subscription Source: https://docs.dintero.com/partners/subscriptions/aid_source_hooks_hid_delete /mintlify-docs/openapi/spec-webhooks.yaml delete /accounts/{aid}/hooks/subscriptions/{hid} Delete a webhook subscription No more events will be sent to the webhook scopes: - admin:hooks - write:hooks # Get subscription details Source: https://docs.dintero.com/partners/subscriptions/aid_source_hooks_hid_get /mintlify-docs/openapi/spec-webhooks.yaml get /accounts/{aid}/hooks/subscriptions/{hid} Get subscription details scopes: - admin:hooks - read:hooks # Create subscription Source: https://docs.dintero.com/partners/subscriptions/aid_source_hooks_post /mintlify-docs/openapi/spec-webhooks.yaml post /accounts/{aid}/hooks/subscriptions When you create a new webhook, we'll send you a simple ping event to let you know you've set up the webhook correctly. You can trigger a ping again by calling the [ping endpoint](/webhooks-api/subscription-deliveries/aid_source_hooks_hid_ping_post). ## Receiving Webhooks In order for Dintero to send webhook payloads, your server needs to be accessible from the Internet. We also highly suggest using SSL so that we can send encrypted payloads over HTTPS. ## Respond to a webhook Your webhook acknowledges that it received data by sending a 200 OK response. Any response outside of the 200 range will let Dintero know that you did not receive your webhook, including 301 Redirect. Dintero does not follow redirects for webhook notifications and will consider a redirection as an error response. Dintero has implemented a 60-second timeout period and a retry period for subscriptions. We wait 120 seconds for a response to each request, and if there isn't one or we get an error, we retry the connection to a total of 5 times. A webhook will be deleted if there are consecutive failures for the exact same webhook. You should monitor the admin of your webhook tool for failing webhooks. ### Webhooks Headers Dintero will send along several HTTP headers to differentiate between event types and payload identifiers. | Name | Description | |----------------|------------------------------------------------------| | event | The event type | | event-delivery | A guid to indentify the payload and event being sent | | event-signature| The value of this header is computed as the HMAC SHA1 hex digest of the body, using the secret config option as the key. | scopes: - admin:hooks - write:hooks