Skip to content

Elavon

Process card payments through Elavon, with 3-D Secure by Endeavour: the contract, the test cards and the settlement IDs.

For PayFacs and ISOs that process through Elavon. Ginger sends card payments to Elavon, and authenticates the customer with 3-D Secure (3DS) through Endeavour, a 3DS server. You configure the Elavon merchant IDs and terminal ID per project, in a contract.

How it works

Elavon is the card processor of your platform, or of the merchants you assign to it (see Payments). A card payment through Elavon goes like this:

  1. The customer enters the card details on the hosted payment page, or in the merchant's own checkout. Ginger stores the card in its vault.
  2. Ginger authenticates the customer through Endeavour, with 3DS 2.1 or 2.2. The issuer lets the payment through (frictionless flow), or asks the customer to confirm it (challenge flow).
  3. Ginger sends the authorised payment to Elavon. The transaction is processing until Elavon responds, then becomes accepted (Approved at Elavon) or error (Denied at Elavon).
  4. Ginger sends Elavon settlement files with the payments and refunds, and checks Elavon's reports against them. See Settlement IDs.

Your merchants integrate Elavon card payments and refunds like any other: see Accept a card payment and Refunds in the payment acceptance docs.

Elavon processes sales: the amount is captured with the authorisation. Pre-authorisations with a manual or delayed capture aren't supported through Elavon.

Elavon
Payment methodscredit-card, apple-pay, google-pay
Card brandsVisa, Mastercard, American Express
3-D SecureEndeavour, 3DS 2.1 and 2.2, with low value exemptions
Sale and refundYes
Pre-authorisation and captureNo
One-click paymentsYes. The CVC is optional for subsequent payments. Switch on per merchant: see Merchant card settings
Recurring paymentsYes. Switch on per merchant: see Merchant card settings
Zero-amount authorisationFor the first one-click or recurring payment

When a payment qualifies for a low value exemption, Ginger sends it to Elavon without 3DS. When the issuer declines it with a soft decline, the customer authenticates with 3DS and Ginger retries the payment.

Contract

Elavon gives you a merchant ID (MID) per card brand and a terminal ID (TID). Ask your Ginger contact who provides the merchant identifier at Endeavour. Fill them in on the Elavon contract of the project: in the Admin portal, open the project, go to the Payment Method Contracts tab, switch on Elavon and open it. With the Boarding API, set the ginger-elavon contract of the project.

Give at least one MID, in acceptor_id_visa, acceptor_id_mastercard or acceptor_id_amex, plus the acceptor_terminal_id and the endeavour_merchant_id. See the ginger-elavon fields of Update a project contract in the API reference.

curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/projects/$PROJECT_ID/contracts/ginger-elavon/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --request PUT \
  --data '{
    "acceptor_id_visa": "<Visa MID>",
    "acceptor_id_mastercard": "<Mastercard MID>",
    "acceptor_terminal_id": 1,
    "endeavour_merchant_id": "<Endeavour merchant identifier>"
  }'

The project also needs permission for /payment-methods/credit-card/ with POST: see Permissions.

Elavon also receives the card acceptor details of each payment, so these must be filled in before the first payment:

  • the trade name and the website URL of the project;
  • the billing address of the merchant: address line, postal code, city and country.

A project with a missing field can't start Elavon payments: the transaction is refused with a message that names what's missing.

The currencies and the low value exemptions of an Elavon project are set in its Credit Card contract (currencies, low_value_exemptions). Without currencies, the project accepts only EUR.

Statuses

Elavon answers asynchronously, for payments and for refunds. In the Admin portal, an Elavon transaction goes through these statuses:

Transaction statusReasonMeaning
pendingThe customer is authenticating with 3DS. Payments only
processingSent to Elavon, no answer yet. The customer is already back on the merchant's page
acceptedApproved at ElavonElavon approved the payment or refund
errorDenied at ElavonElavon or the issuer declined it. elavon_response_code and elavon_advice_code hold the codes
errorTimed out at Elavon or Invalid response at ElavonNo valid answer from Elavon
error3DS authentication failed. Payments only
expiredThe customer didn't finish the payment in time

The payment_method_details of an Elavon payment, and of its refund (credit-card-refund), hold:

FieldContent
gatewayginger-elavon
3ds_method_usedchallenge or frictionless. Payments only
elavon_approval_codeApproval code from Elavon, when approved
elavon_response_code, elavon_advice_codeElavon's response code and merchant advice code, when declined
transaction_idElavon's retrieval reference number
external_batch_idThe Elavon reconciliation batch: date and number, such as 2026-03-05-1

For all statuses, see Statuses. For the response codes, see Error reasons.

Test data

Test with a project in test mode (status active-testing). Test payments go to the Elavon and Endeavour test environments.

In the challenge flow, the test 3DS page asks for a one-time password: 555 succeeds, any other code fails. Use the expiry date 07/2028 with every card.

Visa and Mastercard

BrandCard numberCVC3DS flowResult
Visa4918914107195005123ChallengeFully authenticated
Visa4001880000000055123ChallengeCancelled by the merchant
Visa4907639999990022123FrictionlessAuthentication rejected
Visa4907630099999922123FrictionlessNot authenticated (denied)
Mastercard5283901906612672156FrictionlessAuthentication rejected
Mastercard5283901901266672156FrictionlessNot authenticated (denied)
Mastercard5283901901626677156FrictionlessAuthentication attempted
Mastercard5185570141917102156FrictionlessWith amount 1278 and a low value exemption: soft declined, then successful after 3DS

American Express

For these cards, the amount of the order decides the outcome. Amounts are in the smallest currency unit: 100 is 1.00. All use the frictionless flow and CVC 1234.

Card numberAmountResult
374500262001008100 to 1000Fully authenticated
3745002610010091100 to 2000Fully authenticated
3745002610010092100 to 3100Authentication attempted
3745002620010083100 to 4000Authentication attempted
3745002610010096100 to 7000Unable to authenticate

The response codes of declined payments are in payment_method_details.elavon_response_code and elavon_advice_code. See Error reasons.

Settlement IDs

Ginger puts the ID of each transaction in the transaction detail record (TDR) of the settlement file it sends to Elavon. The field is too short for a UUID, so Ginger encodes the ID in base 32 and drops the padding: ada78fe2-1654-4ef6-8ac8-6d5973cb5f2a becomes VWTY7YQWKRHPNCWINVMXHS27FI.

To match Elavon's settlement data with the transactions on your platform, decode the ID back to the transaction ID:

import uuid, base64

def decoded_transaction_id(transaction_id: str) -> str:
    padded = transaction_id + '=' * (-len(transaction_id) % 8)
    return str(uuid.UUID(bytes=base64.b32decode(padded)))

This is how Ginger encodes it:

import uuid, base64

def encoded_transaction_id(transaction_id: str) -> str:
    transaction_id_bytes = uuid.UUID(transaction_id).bytes
    return base64.b32encode(transaction_id_bytes).decode().rstrip('=')[:30]

Each Elavon transaction also has external_batch_id and transaction_id in payment_method_details: see Statuses.

Next steps