Increase Approval Rate

F.1 — Why Approval Rate Matters

The approval rate is the percentage of authorisation attempts approved by the card issuer. It is a direct revenue metric: every declined transaction that should have been approved is lost revenue.

Industry benchmark: E-commerce merchants typically operate between 85% and 95% authorisation rate. Approximately 15% of card-not-present transactions are declined across the industry. The majority are for reasons unrelated to fraud or insufficient funds.

Common causes of avoidable declines:

Insufficient data sent to the issuer (missing address, phone, or email)
Soft declines due to missing or incomplete 3DS2 browser data
IP address or fingerprint inconsistency flagged as risk signal
MCC mismatch between registered category and actual transaction type
Stale PAN — card expired or replaced without account updater data

A decline from the issuer does not mean fraud. Treating it as such and blocking retries is one of the most common causes of revenue loss.

F.2 - Required vs Optional Fields

Minimum required fields

The following fields are required to create a transaction:

{
  "customerId": "{{customerId}}",
  "currency": "USD",
  "amount": 99,
  "type": "sale",
  "paymentInstruction": {
    "paymentInstrumentId": "{{paymentInstrumentId}}"
  }
}

Full recommended payload

Sending the complete data set materially increases approval rates. Add the following to every transaction request where available:

{
  "customerId": "{{customerId}}",
  "currency": "USD",
  "amount": 99,
  "type": "sale",
  "redirectUrl": "https://yoursite.com/{id}/{result}",
  "paymentInstruction": {
    "paymentInstrumentId": "{{paymentInstrumentId}}"
  }
}

Customer enrichment data (name, address, phone, email) is set on the Customer object and the Payment Instrument at the time of tokenization (see F.3 Customer Data Enrichment and F.4 riskMetadata at Tokenization below).

Note:

redirectUrl is optional, but strongly recommended for 3DS flows. Without it, the customer has no defined return path after completing 3DS authentication. Use the pattern https://yoursite.com/{id}/{result}: {id} is populated with the transaction ID and {result} with the outcome after the transaction completes.

F.3 — Customer Data Enrichment

The following fields are passed when creating or updating a Customer record and when creating the Payment Instrument token. Issuers generally use this kind of data to score transaction risk, so sending more complete and accurate data tends to reduce avoidable declines. The exact weighting is determined by each issuer, not by PaymentsAI.

Customer fields

Field	Format	Notes
`firstName`	string	Customer's first name.
`lastName`	string	Customer's last name.
`email`	valid email address	Prefer a real, verified address over a placeholder such as `test@` or `noreply@`. A verified email is generally a positive risk signal.
`phoneNumber`	string	The customer's phone number, for example `123-456-7890`. A complete, valid number is generally a positive risk signal.

Billing address fields

Billing address is set as the billingAddress object on the tokenization request (see F.4 and the Tokenization Endpoint guide). Populating all subfields is recommended. The postalCode typically feeds the issuer's AVS (Address Verification System) check. Where AVS applies, a postal code that does not match the card-issuing bank's records is a common contributor to declines.

Field	Notes
`address`	Street address
`city`	—
`region`	State or region code
`postalCode`	Must match the postal code registered with the card issuer
`country`	ISO 3166-1 alpha-2 (e.g. `US`, `DE`)

Note — field names differ by endpoint:

Creating a Customer uses primaryAddress with a zip field (see Create a customer with a payment instrument).

Tokenization (including FramePay) uses billingAddress with a postalCode field.

Use the field names that match the endpoint you are calling.

F.4 — riskMetadata at Tokenization

The riskMetadata object is passed during card tokenization. This data is forwarded to the issuer and fraud scoring systems and contributes to 3DS2 frictionless flow eligibility.

Most integrations use FramePay:

If you tokenize with FramePay (the recommended client-side approach), pass the extra data through the extraData argument of Framepay.createToken(form, extraData). The billingAddress object inside extraData accepts firstName, lastName, organization, address, address2, city, region, country, postalCode, plus phoneNumbers and emails arrays. firstName and lastName are required to create a token. The more billing and contact data you provide here, the better the issuer can score the transaction. See the FramePay API reference.

The server-to-server tokenization request below shows the full riskMetadata object. The same risk and billing data improves approval rates whichever tokenization method you use.

curl -i -X POST \
  'https://tokenization.payments.ai/tokens' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: ApiKey <keyValue>' \
  -H 'X-Organization-Id: <orgId>' \
  -d '{
    "method": "payment-card",
    "paymentInstrument": {
      "pan": "4111111111111111",
      "expMonth": 12,
      "expYear": 2030,
      "cvv": "737"
    },
    "billingAddress": {
      "firstName": "Joe",
      "lastName": "Doe",
      "address": "123 Main St",
      "city": "Springfield",
      "region": "NY",
      "postalCode": "10009",
      "country": "US"
    },
    "riskMetadata": {
      "ipAddress": "93.92.91.90",
      "fingerprint": "pIUt3xbgX3l9g3YDiLbx",
      "httpHeaders": {
        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
      },
      "browserData": {
        "colorDepth": 24,
        "isJavaEnabled": true,
        "language": "en-US",
        "screenWidth": 1920,
        "screenHeight": 1080,
        "timeZoneOffset": 300,
        "isAdBlockEnabled": false
      },
      "extraData": {
        "kountFraudSessionId": "abcdefg12345abababab123456789012",
        "payPalMerchantSessionId": "dd65ratxc5qv15iph3vyoq7l6davuowa",
        "threatMetrixSessionId": "dd65ratxc5qv15iph3vyoq7l6davuowa"
      }
    }
  }'

riskMetadata fields

Field	Type	Description
`ipAddress`	string	Shopper's IP address at the time of payment. An IP whose geolocation is consistent with the billing country is generally a positive risk signal.
`fingerprint`	string	Device fingerprint generated client-side. Keeping it stable across sessions for the same returning customer generally helps risk scoring.
`httpHeaders.Accept`	string	Browser `Accept` header from the shopper's request.
`browserData.colorDepth`	integer	Screen colour depth in bits.
`browserData.isJavaEnabled`	boolean	Whether Java is enabled in the browser.
`browserData.language`	string	Browser language (e.g. `en-US`).
`browserData.screenWidth`	integer	Screen width in pixels.
`browserData.screenHeight`	integer	Screen height in pixels.
`browserData.timeZoneOffset`	integer	UTC offset in minutes (e.g. `300` = UTC-5).
`browserData.isAdBlockEnabled`	boolean	Whether an ad blocker is active.
`extraData.kountFraudSessionId`	string	Session ID from Kount fraud platform, if used.
`extraData.payPalMerchantSessionId`	string	Session ID from PayPal risk tools, if used.
`extraData.threatMetrixSessionId`	string	Session ID from ThreatMetrix, if used.

Note:

PAI does not store raw card data. The pan and cvv fields are tokenized immediately. The platform handles PCI DSS scope reduction for you.

F.5 — 3D Secure (3DS2) / SCA

Overview

3Ds2 adds a cardholder authentication step between payment submission and issuer authorisation. It can result in either a frictionless flow (authentication happens silently) or a challenge flow (the customer completes an additional verification step).

EU/UK merchants: 3DS is mandatory under PSD2 SCA for transactions with EU and UK cardholders.
Global merchants: 3DS reduces fraud and shifts liability to the issuer for authenticated transactions.

3DS is disabled by default for all gateways. See Business Decision Matrix for activation steps.

Frictionless vs challenge flow

The issuer decides which flow applies based on the risk data it receives. Sending complete browserData, a consistent fingerprint, an ipAddress that matches the billing country, and a known returning customer history increases the probability of a frictionless outcome.

Transaction flow

Step 1 — Create the transaction

curl --location 'https://staging-api.payments.ai/v1/public-api/organizations/:organizationId/transactions' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey <keyValue>' \
--data '{
    "customerId": "{{customerId}}",
    "currency": "USD",
    "amount": 99,
    "type": "sale",
    "paymentInstruction": {
        "paymentInstrumentId": "{{paymentInstrumentId}}"
    },
    "redirectUrl": "https://yoursite.com/{id}/{result}"
}'

Step 2 — Check the response

If 3DS is required, the response returns status: "waiting" and an approvalLink:

{
  "data": {
    "id": "txn_abc123",
    "status": "waiting",
    "result": "unknown",
    "approvalLink": "https://3ds.example/..."
  }
}

If 3DS is not required, the transaction completes immediately:

{
  "data": {
    "id": "txn_abc123",
    "status": "completed",
    "result": "approved"
  }
}

Step 3 — Redirect the customer (challenge flow)

When status is waiting, redirect the customer to the approvalLink. The customer completes authentication with their card issuer.

Step 4 — Handle the return

After authentication, the customer is redirected to your redirectUrl with the transaction ID and result appended:

https://yoursite.com/txn_abc123/approved
https://yoursite.com/txn_abc123/declined

Poll the transaction by ID or handle the result via webhook to confirm the final result and status.

Transaction statuses

The statuses most relevant to the 3DS flow are below. This is a subset; a transaction can also be refunded, partially-refunded, voided, disputed, and others. For the full status set, see the transaction schema in the Webhooks reference.

Status	Meaning
`waiting`	3DS authentication required (redirect customer to `approvalLink`)
`completed`	Transaction finished (check `result` for outcome)
`offsite`	Transaction processing off-platform
`timeout`	Authentication or processing timed out

Transaction results

Result	Meaning
`approved`	Authorised by issuer
`declined`	Declined by issuer or fraud system
`abandoned`	Customer did not complete authentication
`canceled`	Transaction was voided
`unknown`	Final result not yet determined

F.6 — MCC Code Matching

A Merchant Category Code (MCC) is a four-digit code assigned to your account that classifies your business type. The MCC is submitted with every transaction and is used by issuers to assess transaction risk.

If the MCC does not match the nature of the transaction:

The issuer's fraud models flag the mismatch as a risk signal
Decline rates increase for that transaction type
Interchange fees may be higher than necessary (high-risk MCC = higher interchange)
Compliance issues may arise for regulated categories

MCC per supported business category

PaymentsAI assigns the MCC during onboarding based on the business category you selected with your Integration Consultant. The mapping is:

Business category	Recommended MCC	Description / notes
BUSINESS SERVICES	7399	Business Services, Not Elsewhere Classified
EDUCATION	8299	Schools and Educational Services - Not Elsewhere Classified
PERSONAL SERVICES	7299	Miscellaneous Personal Services (e.g. spas, diet centers)
PHYSICAL_GOODS	5999	Miscellaneous and Specialty Retail Stores (default generic)
SOFTWARE	5734	Computer Software Stores
NUTRACEUTICALS	5499	Misc. Food Stores - Convenience / Specialty (used for health foods)
SUPPLEMENTS	5499	Often grouped with Nutraceuticals; occasionally 5912 (Drug Stores)
ACCOUNTING	8931	Accounting, Auditing, and Bookkeeping Services
COSMETIC STORES	5977	Cosmetic Stores
BEAUTY SHOPS	7230	Barber and Beauty Shops
OTHER	5999	Miscellaneous and Specialty Retail Stores

Important:

Using the wrong MCC (for example, coding a SaaS subscription as general retail) increases your decline rate and may result in higher interchange fees and compliance review.

Your MCC is set during KYC onboarding and must reflect your business activity. Confirm the correct MCC with your Integration Consultant during Discovery. See Business Category & Document Matrix for category-level guidance.

F.7 — Retry Logic

Soft vs hard declines

When a transaction is declined, the decline falls into one of two broad categories. The merchant is responsible for categorising each decline and applying retry logic accordingly.

Soft declines are transient: the card is valid but the transaction cannot be processed right now (for example, a temporary hold, insufficient funds, or an issuer system being briefly unavailable). Retrying later is appropriate.

Hard declines are permanent: the card or account cannot be used for this transaction (for example, an expired, lost, or stolen card, or an issuer flagging the transaction as fraud). Do not retry.

Important:

Retrying a hard decline increases your decline ratio, raises your risk score with the issuer, and can result in the card being permanently flagged against your merchant ID.

For the full list of decline reasons returned by the platform, see the Decline Codes reference.

Dunning for subscriptions

For recurring billing, configure your dunning schedule in the dashboard under Subscriptions → Dunning Rules. A typical retry schedule for a failed subscription payment:

Attempt	Timing
1 (initial)	Day 0
2	Day +1
3	Day +3
4	Day +5
5	Day +7
No response	`past_due` → `churned`

The schedule is configurable per your business model. Earlier retries work better for soft declines caused by temporary holds; later retries are better for insufficient funds that may clear on a pay cycle.

F.8 — Expected Impact by Optimisation

The figures below are industry benchmarks based on card-not-present transaction data. They show typical uplift ranges. Results depend on your starting baseline, traffic mix, and geography.

Optimisation	Typical uplift
Full billing address (all subfields)	+3–8%
`phoneNumber` in correct format	+1–3%
Verified email address	+1–2%
ZIP matching card issuer records (AVS)	+2–5%
`ipAddress` + `fingerprint` in `riskMetadata`	+2–4%
Full `browserData` (3DS2 frictionless)	+5–10% (EU traffic)
`extraData` with fraud session IDs	+1–3%
Smart retry logic for soft declines	+1–4% (subscription retention)
Correct MCC	+1–3%

Note:

These benchmarks reflect industry data for card-not-present e-commerce. Uplift for any single optimisation depends on your current data completeness. The largest gains come from merchants sending incomplete data today.

F.1 — Why Approval Rate Matters​

F.2 - Required vs Optional Fields​

Minimum required fields​

Full recommended payload​

F.3 — Customer Data Enrichment​

Customer fields​

Billing address fields​

F.4 — riskMetadata at Tokenization​

riskMetadata fields​

F.5 — 3D Secure (3DS2) / SCA​

Overview​

Frictionless vs challenge flow​

Transaction flow​

Transaction statuses​

Transaction results​

F.6 — MCC Code Matching​

MCC per supported business category​

F.7 — Retry Logic​

Soft vs hard declines​

Dunning for subscriptions​

F.8 — Expected Impact by Optimisation​