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:
- 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.
- 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).
- Ginger sends the authorised payment to Elavon. The transaction is
processinguntil Elavon responds, then becomesaccepted(Approved at Elavon) orerror(Denied at Elavon). - 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 methods | credit-card, apple-pay, google-pay |
| Card brands | Visa, Mastercard, American Express |
| 3-D Secure | Endeavour, 3DS 2.1 and 2.2, with low value exemptions |
| Sale and refund | Yes |
| Pre-authorisation and capture | No |
| One-click payments | Yes. The CVC is optional for subsequent payments. Switch on per merchant: see Merchant card settings |
| Recurring payments | Yes. Switch on per merchant: see Merchant card settings |
| Zero-amount authorisation | For 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_, acceptor_ or acceptor_, plus the
acceptor_ and the endeavour_. 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 / 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_). 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 status | Reason | Meaning |
|---|---|---|
pending | The customer is authenticating with 3DS. Payments only | |
processing | Sent to Elavon, no answer yet. The customer is already back on the merchant's page | |
accepted | Approved at Elavon | Elavon approved the payment or refund |
error | Denied at Elavon | Elavon or the issuer declined it. elavon_ and elavon_ hold the codes |
error | Timed out at Elavon or Invalid response at Elavon | No valid answer from Elavon |
error | 3DS authentication failed. Payments only | |
expired | The customer didn't finish the payment in time |
The payment_ of an Elavon payment, and of its refund (credit-card-refund), hold:
| Field | Content |
|---|---|
gateway | ginger-elavon |
3ds_ | challenge or frictionless. Payments only |
elavon_ | Approval code from Elavon, when approved |
elavon_, elavon_ | Elavon's response code and merchant advice code, when declined |
transaction_ | Elavon's retrieval reference number |
external_ | The 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/ with every card.
Visa and Mastercard
| Brand | Card number | CVC | 3DS flow | Result |
|---|---|---|---|---|
| Visa | 4918914107195005 | 123 | Challenge | Fully authenticated |
| Visa | 4001880000000055 | 123 | Challenge | Cancelled by the merchant |
| Visa | 4907639999990022 | 123 | Frictionless | Authentication rejected |
| Visa | 4907630099999922 | 123 | Frictionless | Not authenticated (denied) |
| Mastercard | 5283901906612672 | 156 | Frictionless | Authentication rejected |
| Mastercard | 5283901901266672 | 156 | Frictionless | Not authenticated (denied) |
| Mastercard | 5283901901626677 | 156 | Frictionless | Authentication attempted |
| Mastercard | 5185570141917102 | 156 | Frictionless | With 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 number | Amount | Result |
|---|---|---|
374500262001008 | 100 to 1000 | Fully authenticated |
374500261001009 | 1100 to 2000 | Fully authenticated |
374500261001009 | 2100 to 3100 | Authentication attempted |
374500262001008 | 3100 to 4000 | Authentication attempted |
374500261001009 | 6100 to 7000 | Unable to authenticate |
The response codes of declined payments are in payment_ and elavon_. 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_ and transaction_ in payment_: see Statuses.
Next steps
- Processor contracts: contracts and low value exemptions.