# Affirm source: https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/alt-pay-methods/a2a/affirm/index.md ## Overview {#overview} Affirm is a Buy Now, Pay Later (BNPL) payment method. It allows customers to purchase goods and services and pay in installments. At checkout, customers can: * Select **Affirm**. * Complete a quick application, which involves a soft credit check. * Choose from flexible payment plans, such as Pay in 4 with four interest-free payments or monthly installments ranging from 3 to 36 months. The annual percentage rate ranges from 0 percent to 36 percent, depending on credit and loan terms. Affirm is mainly used in the United States and is supported by many retailers. For more information, refer to [Affirm](https://www.affirm.com/). ## Prerequisites {#prerequisites} To offer the Affirm payment method through the Mastercard Gateway: 1. Register with your payment method service provider. 2. Register with Affirm as a merchant. 3. Configure your merchant profile in Mastercard Gateway using the details provided by your payment provider. ## Payer journey flow {#payer-journey-flow} The payer journey flow includes: 1. The customer selects products or services and proceeds to checkout. 2. The customer provides basic details, such as name, email, phone, and address. 3. The customer selects Affirm as the payment method. 4. The customer is redirected to the Affirm page and logs in. 5. The customer authorizes the payment. 6. The customer is redirected back to the merchant site with the payment status. 7. If the payment fails, the customer can choose another payment method. ![Affirm payment payer journey flow](https://static.developer.mastercard.com/content/mastercard-gateway/uploads/affirm.png) ## Affirm payments integration {#affirm-payments-integration} ### Affirm payments through Direct Payment {#affirm-payments-through-direct-payment} Affirm paymennts through Drect Payment includes: * Direct Payment integration allows you to offer Affirm payments on your own checkout page. * Affirm payments is supported from the WS-API version 100 onwards. * Make an Initiate Browser Payment request where 'sourceOfFunds.browserPayment.type = AFFIRM' and 'browserPayment.operation = PAY'. ### AffirmPay Transactions {#affirmpay-transactions} | Transaction details | Value | |-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| | Payment type | BNPL | | Supported countries | CANADA, USA | | Supported currencies | CAD, USD | | Supported operations | PURCHASE (PAY), FULL REFUND, PARTIAL REFUND | | Minimum transaction amount | 0 | | Maximum transaction amount | 1000000000000 | | Refund validity | Not applicable. Refunds are not available through Mastercard Gateway. | | Chargeback | Not applicable | | Transaction validity period | Five minutes. Default timeout period is five minutes and if any value, such as one minute, is configured in the merchant portal, then it becomes six minutes. | ### Payment Options Inquiry {#payment-options-inquiry} You can use a Payment Option Inquiry (POI) request to retrieve the payment options available to them and their associated attributes. The POI response can contain information about mandatory and optional fields, in addition to standard fields, limits, and general payment plan offer information for BNPL payment methods. ```bash curl --request POST https://{{host}}.gateway.mastercard.com/api/rest/version/latest/merchant/OPTTY_MER1/paymentOptionsInquiry ``` ```json { "merchant": "OPTTY_MER1", "paymentTypes": { "browserPayment": [ { "currencies": [ { "currency": "USD" } ], "description": "Affirm is a BNPL provider. It operates in the United States, Canada and Great Britain", "displayName": "Affirm", "logoUrl": "https://test-regression-brand1.qa06.gateway.mastercard.com/bpui/bp/logo/cb83b6d3-1322-47b8-9a5d-a1ca5ad61b43_AFFIRM.svg", "maxAmount": 1000000000000, "minAmount": 0, "paymentPlanOffer": [ { "currency": "USD", "customerFee": false, "interestRate": 0, "lateFee": false, "paymentAmount": 0, "timeBetweenPayments": { "count": "12", "unitOfMeasure": "MONTH" } } ], "standardPayerData": [ { "fieldName": "PHONE", "presence": "OPTIONAL" }, { "fieldName": "EMAIL", "presence": "OPTIONAL" }, { "fieldName": "BILLING_ADDRESS", "presence": "OPTIONAL" }, { "fieldName": "SHIPPING_ADDRESS", "presence": "OPTIONAL" }, { "fieldName": "FIRST_NAME", "presence": "OPTIONAL" }, { "fieldName": "LAST_NAME", "presence": "OPTIONAL" } ], "supportedCountries": [ { "country": "USA" } ], "type": "AFFIRM" } ] }, "result": "SUCCESS", "supportedPaymentOperations": [ { "supportedPaymentOperation": "PURCHASE" } ] } ``` ### Specific parameter fields {#specific-parameter-fields} In addition to the [standard fields](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/alt-pay-methods/imp-brow-pay-int/index.md#browser-payments-through-hosted-checkout-integration) required in a browser payment request, include the following specific parameter fields in the [Initiate Browser Payment](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#browser-payment) request for AffirmPay. | Parameter name | Mandatory or Optional | Description | |----------------------|-----------------------|------------------------------------| | `customer.email` | Optional | Payer email information | | `customer.firstName` | Optional | Payer first name | | `customer.lastName` | Optional | Payer last name | | `customer.phone` | Optional | Payer phone number | | `billing.address` | Optional | Billing address information | | `shipping.address` | Optional | Shipping address information | | `item` | Optional | Item details for the transaction | | `order.currency` | Mandatory | Order currency for the transaction | Note: Shipping address is required for Affirm Canadian Dollar (CAD). ### Initiate Affirm payments {#initiate-affirm-payments} ```json { "apiOperation": "INITIATE_BROWSER_PAYMENT", "billing": { "address": { "city": "Edinburgh", "company": "MPGS", "country": "USA", "stateProvince": "CA", "street": "OceanPoint", "street2": "OceanDrive", "postcodeZip": "12345" } }, "shipping": { "address": { "city": "Edinburgh", "company": "MPGS", "country": "USA", "stateProvince": "CA", "street": "OceanPoint", "street2": "OceanDrive", "postcodeZip": "12345" } }, "browserPayment": { "operation": "PAY", "returnUrl": "{{host}}/api/documentation/integrationGuidelines/index.html" }, "customer": { "account": { "id": "customerAccount" }, "dateOfBirth": "1999-12-31", "email": "developer+au@optty.com", "firstName": "Akash", "lastName": "Mali", "nationalId": "nationalId1", "phone": "415-333-4568" }, "order": { "reference": "TEST-SUCCEED", "amount": "9.00", "itemAmount": "9.00", "currency": "USD" }, "sourceOfFunds": { "browserPayment": { "type": "AFFIRM" }, "type": "BROWSER_PAYMENT" } } ``` ```json { "billing": { "address": { "city": "San Francisco", "company": "MPGS", "country": "USA", "postcodeZip": "94105", "stateProvince": "CA", "street": "OceanPoint", "street2": "OceanDrive" } }, "browserPayment": { "interaction": { "status": "INITIATED", "timeInitiated": "2025-11-17T13:52:04.233Z" }, "operation": "PAY", "redirectHtml": "
", "returnUrl": "{{host}}/api/documentation/integrationGuidelines/index.html" }, "customer": { "account": { "id": "customerAccount" }, "email": "developer+au@optty.com", "firstName": "Akash", "lastName": "Mali", "nationalId": "nationalId1", "phone": "415-333-4568" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "OPTTY_MER1", "order": { "amount": 9, "chargeback": { "amount": 0, "currency": "USD" }, "creationTime": "2025-11-17T13:52:04.193Z", "currency": "USD", "id": "2165548091", "itemAmount": 9, "lastUpdatedTime": "2025-11-17T13:52:05.859Z", "merchantAmount": 9, "merchantCurrency": "USD", "reference": "TEST-SUCCEED", "status": "INITIATED", "totalAuthorizedAmount": 0, "totalCapturedAmount": 0, "totalDisbursedAmount": 0, "totalRefundedAmount": 0 }, "response": { "acquirerCode": "ACCEPTED", "gatewayCode": "SUBMITTED", "gatewayRecommendation": "NO_ACTION" }, "result": "SUCCESS", "shipping": { "address": { "city": "San Francisco", "company": "MPGS", "country": "USA", "postcodeZip": "94105", "stateProvince": "CA", "street": "OceanPoint", "street2": "OceanDrive" } }, "sourceOfFunds": { "browserPayment": { "type": "AFFIRM" }, "type": "BROWSER_PAYMENT" }, "timeOfLastUpdate": "2025-11-17T13:52:05.859Z", "timeOfRecord": "2025-11-17T13:52:04.225Z", "transaction": { "acquirer": { "id": "OPTTY_QA_TESTACQ1", "merchantId": "R1BXsx0cmZCms6ir" }, "amount": 9, "currency": "USD", "id": "9234485063", "source": "INTERNET", "stan": "0", "type": "PAYMENT" }, "version": "100" } ``` ## Interpretation of the transaction result {#interpretation-of-the-transaction-result} This table shows the transaction response codes for the possible scenarios that you may encounter after initiating the Affirm payments. | Initiate browser payment response | What this means | |-------------------------------------------------------|------------------------------------------------------------| | `response.gatewayCode = SUBMITTED` `result = SUCCESS` | Redirect the payer using the URL provided in the response. | | Retrieve transaction or retrieve order response | What this means | |-------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `response.gatewayCode = APPROVED` `result = SUCCESS` | The payment is successful. | | `response.gatewayCode = PENDING` `result = PENDING` | The Mastercard Gateway is waiting for a confirmation from the acquirer about the payment result. Retry `RETRIEVE_TRANSACTION` or listen to notifications from the Mastercard Gateway. | | `response.gatewayCode = CANCELLED` `result = FAILURE` | The payer has cancelled the interaction for this payment. Offer the payer the option to try another payment method. | | `response.gatewayCode = DECLINED or ACQUIRER_SYSTEM_ERROR` `result = FAILURE` | The payment was declined. Offer the payer the option to try another payment method. In the case of an `ACQUIRER_SYSTEM_ERROR`, you may inquire with the acquirer for the reason for payment failure, or retry the `RETRIEVE_TRANSACTION`. | | `response.gatewayCode = TIMED_OUT` `result = FAILURE` | Treat as declined. The Mastercard Gateway ensures the transaction is not successful or reverts the transaction. | ## AffirmPay through Hosted Checkout {#affirmpay-through-hosted-checkout} Hosted Checkout integration allows you to collect payment details from your payer through an interaction that the gateway hosts and displays. From the API version 85 and later, AffirmPay payments is automatically available as a payment method once your payment service provider enables and configures you for this payment method. For more information, see [Browser Payments through Hosted Checkout integration](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/alt-pay-methods/imp-brow-pay-int/index.md#browser-payments-through-hosted-checkout-integration). ## Webhook notifications {#webhook-notifications} If you have subscribed to Mastercard Gateway webhook notifications, you will receive additional notifications on the paymentStatus.