Getting started
Coming soonPrepare your existing merchant integration: account access, checkout and payment results.
Etail APIs and tools are not available yet. This guidance is for existing merchant connections.
On this page
Integration requirements
Confirm the merchant accounts, permissions and connection specifications for your setup.
Before you begin
- The services and operations your integration needs
- The business and account references already available to your team
- Contacts for engineering and payment operations
Request your account specifications
Account permissions and the operations available to your connection.
The specifications and access instructions for your account.
Contact the integration teamMap your connections
A portal login does not grant API access. Confirm which services and operations your business needs; reporting access alone does not permit refunds, adjustments or funding instructions.
- Account serviceApplication accessProgram and environment
- Checkout servicePayment accessProcessing account and environment
- Reporting serviceRecord accessAccount access and permissions
Keep account identities distinct
Map your business record to the identifiers assigned for the application, processing and reporting services. Store sandbox and production mappings separately.
Check account permissions on your server
Start from the authenticated user and your own business record. Determine the permitted merchant and operation before making an external request.
Check the returned account
Compare the response with the expected merchant mapping. Do not display a record from a different merchant, even when the API request itself succeeded.
| Record | How to use it |
|---|---|
| Your business ID | Your stable identifier for the business using your platform. On your server, check whether the user who is signed in has access to it. |
| Application and program | The application reference and any program identifier assigned to it. Keep the review decision and setup results with that application. |
| Processing account | The merchant or organization identifiers assigned for processing. Keep distinct identifiers separate where the integration requires more than one. |
| Reporting account | The account or tenant that controls reporting access and the merchant whose records may be read. Confirm the account references in your integration documentation. |
| Environment | Keep a separate mapping for sandbox and production. A matching label or identifier is not evidence that the two environments are interchangeable. |
Changing a merchant ID in a browser request cannot change which account that user is authorized to access.
Protect credentials and permissions
Store secrets in your backend’s protected configuration. Keep them out of browser bundles, URLs, analytics and application logs. Use credentials only for their assigned service and environment.
Rotate or revoke a key
Use the authorized process for managing keys. Verify the replacement in the correct environment before retiring an uncompromised old key. If a secret is exposed, restrict affected access and follow the incident procedure. Send only the key identifier in a support request, never its secret value.
Keep webhook security separate
Incoming events may use separate verification keys or encryption settings. Follow the event documentation; an outbound API credential does not authenticate an incoming notification.
Verify access before changing records
Begin with the documented account lookup without changing records. Confirm both the intended merchant and refused access to other merchants. An HTTP status alone does not establish a payment result or application decision.
| Check | What to establish |
|---|---|
| Identity | The connection returns the records for the intended merchant and environment. |
| Permissions | Access outside the assigned merchant or permitted operation is refused. |
| Request acceptance | A successful connection or accepted request is distinguished from the application decision or payment result. |
| Uncertain operation | An operation with an uncertain result can be traced using its original reference before another attempt. |
Request the connection specifications
Ask our integration team for the specifications for your account. Keep the approved version and configuration with the connection.
- Access and authentication
- Credential format, authentication procedure, key rotation and revocation, permitted operations and separate environment settings.
- Accounts and checkout
- Merchant mappings, website origins, enabled methods, submission and capture responsibilities, and the authoritative payment lookup.
- Events and recovery
- Event field and status definitions, delivery verification or encryption, acknowledgment, retry rules, reporting availability and rate limits.
- Support contacts
- Keep support contacts for access incidents, unresolved payments, refunds, disputes and funding questions up to date.
Checkout integration
Connect the customer’s order to checkout, verify the payment result and recover an interrupted attempt.
Before you begin
- The checkout connection and instructions provided for your merchant account
- Your order, amount, currency and references for each payment attempt
- The payment methods and capture policy confirmed for your setup
- Instructions for verifying results and recovering transactions
Request your account specifications
Checkout instructions, supported display options and enabled payment methods.
Payment status definitions and the process for recovering an interrupted payment.
Contact the integration teamThe checkout flow
- Your orderMerchant account servicePrepare checkout
Order reference, merchant, amount, currency and attempt.
- Merchant account serviceCustomer checkoutPresent the checkout page
Purchase details and the account’s configured payment methods.
- Customer checkoutPayment processingProcess the payment
The customer submits through the checkout connection enabled for the account.
- Payment recordYour applicationVerify and match
Match the account, amount, currency and operation to the original attempt.
- Your applicationYour orderUpdate the order once
Apply the verified result once. Check an unresolved attempt before allowing another payment.
Confirm processing responsibilities
Agree on one payment submission path. Repeated clicks, callbacks and notifications must resolve to the existing attempt rather than trigger another charge.
| Responsibility | Decision |
|---|---|
| Payment submission | Which service submits the payment, and when it is permitted to do so. |
| Authorization and capture | Whether capture follows authorization separately or is included in the configured sale flow. |
| Payment verification | How your application obtains and verifies the result for the original attempt. |
| Repeated interaction | How repeated clicks, reloads and notifications resolve to the existing attempt. |
Prepare the order and payment attempt
Load the order from your server
Confirm that the customer may pay this order and that the order remains payable. Read the merchant, amount and currency from your stored record, not from totals supplied by the browser.
Track the payment attempt
Keep a reference for each attempt to pay the order. Connect it to the order and merchant account, and check for an unresolved attempt when the customer refreshes or opens another tab.
Use your account’s checkout connection
Follow the setup instructions provided through your merchant account service. Keep account credentials on your server and use the environment provided for sandbox or production.
Order changes
Recalculate the payable total on your server and check the existing attempt before starting a new checkout. Do not associate an existing attempt with a different merchant, currency or order total.
Present the checkout page
Show purchase details from the stored order within the checkout presentation supported by your connection. Check desktop and mobile, including cancellation, return to the order and interrupted loading.
Display and return behavior
Confirm the supported display options, website setup and return behavior with our integration team. Follow the supplied instructions rather than assuming an embedded form or a redirect is available.
Closing or reopening checkout
Closing the interface does not cancel a payment already submitted. Check the original attempt before opening another payment flow.
Wallets and bank payments
Use only the methods configured for the account. Confirm the domain, device and account requirements for wallets. ACH has its own authorization, completion and return process; do not apply card authorization or capture labels to it.
Verify and update the order
Verify the payment result
Follow the payment verification or lookup instructions for your integration to check the original attempt. A callback, redirect or HTTP success is not payment approval. Keep an unverifiable result unresolved and follow the recovery procedure.
Match the payment to the attempt
Check the processing account, order or reference mapping, amount, currency, transaction ID and actual operation. Resolve any fields absent from the result through the authoritative payment record. Reject a mismatch instead of attaching the payment to another order.
Update the original order once
Save the verified transaction reference and result in an atomic update to the original attempt. Repeated callbacks and notifications must not create another charge or repeat fulfillment. Authorization, capture and fulfillment remain separate decisions.
| Outcome | Order handling |
|---|---|
| Authorization approved | Record the authorization reference. Follow the merchant’s capture and fulfillment policy; do not label the payment captured. |
| Capture accepted | Record the capture operation and its status. Settlement and bank receipt remain later events. |
| Payment declined | Leave the order unpaid. Offer another permitted attempt only after the decline is confirmed. |
| Pending or unknown | Keep the attempt unresolved and recover its status. Do not mark the order paid or automatically create another charge. |
Recover interrupted attempts
Start with the original order, attempt and transaction references. A timeout or closed page is not proof that processing stopped.
| Situation | Next action |
|---|---|
| Checkout cannot open | Check the environment and checkout settings for your account. Request the relevant error definitions if the cause is unclear. |
| Customer clicks or reloads again | Resolve the original attempt before permitting another payment. |
| Response is missing | Look up the original payment using the recovery procedure for your integration; an immediate empty result is not proof of failure. |
| Payment is confirmed declined | Retain the declined attempt and follow the permitted retry process. |
| Payment is confirmed successful | Update the original order once and retain the verified transaction reference. |
The browser closes or the result never arrives
Use the transaction lookup and verified events supported by your integration. If no transaction ID reached the browser, recover using the server’s stored attempt and supported references. An empty lookup is not proof of failure. Keep the attempt unresolved and contact our integration team if you cannot confirm the result.
Authentication is canceled or fails
Separate a confirmed authentication failure or cancellation from a communication failure. Resolve any uncertain processing state before offering the customer another permitted action. Do not resubmit automatically.
What to record for support
Record the environment, integration version, order and attempt references, available transaction ID, reported error and time. Share the original error information through the support channel without including payment credentials or tokens.
Prepare for launch
Use your sandbox account and enabled payment methods for these checks. Keep the request references, payment result and order state together.
- A successful payment
- The verified merchant, amount, currency and operation match the order. The payment produces only the intended order update.
- An altered order or result
- A changed browser total, wrong account, modified result or reused result from another order is rejected.
- Refresh and concurrent tabs
- Both views resolve the same active attempt. A second submission cannot create a duplicate charge or fulfillment.
- An interrupted response
- Close the browser after submission or interrupt the connection. Recover the original result before offering another attempt.
- Declines and authentication
- Confirm the customer can recover from a decline or canceled authentication without an automatic retry.
- Checkout and device behavior
- Check opening, closing and returning to checkout, including partial loading and interrupted connections. Use enabled wallets on eligible devices and ACH separately where configured.