Affirm - Gr4vy

Affirm is a buy now, pay later (BNPL) payment method that allows eligible buyers to split purchases into installments. Affirm uses a redirect flow where the buyer approves the payment on the Affirm hosted page.

Setup

To sign up for an account visit the sign-up page and fill in the details.

Credentials

When setting up Affirm in the dashboard, configure the following credentials. Contact your Affirm representative to obtain these values.

Public key - Your Affirm public key for client-side authentication.
Private key - Your Affirm private key for server-side authentication.
Merchant name - Your merchant name as registered with Affirm.

Capabilities

Supported countries

Supported currencies

Identifier limitations

payment_service_transaction_id is null on transaction creation and is populated after the buyer approves the transaction.

Required fields

Affirm requires cart items to be included with every transaction. Up to 249 cart items can be provided. Based on the account setup, Affirm might also require buyer billing and shipping details. When not provided, the Affirm transaction might fail with an invalid_request_parameters error code, more specifically with a raw missing_fields error from Affirm.

Integration

The default integration for Affirm uses a redirect to a hosted payments page. Start by creating a new transaction with the following required fields.

var transaction = await client.Transactions.CreateAsync(
  transactionCreate: new TransactionCreate()
  {
    Amount = 1299,
    Currency = "USD",
    Country = "US",
    PaymentMethod =
      TransactionCreatePaymentMethod.CreateRedirectPaymentMethodCreate(
        new RedirectPaymentMethodCreate()
        {
          Method = "affirm",
          Country = "US",
          Currency = "USD",
          RedirectUrl = "https://example.com/callback",
        }
      ),
  }
);

amount := int64(1299)
currency := "USD"
country := "US"
method := components.RedirectPaymentMethodCreateMethodAffirm
redirectUrl := "https://example.com/callback"

redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
  Method: method,
  Country: country,
  Currency: currency,
  RedirectURL: redirectUrl,
}
paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)

transactionCreate := components.TransactionCreate{
  Amount:        amount,
  Currency:      currency,
  Country:       &country,
  PaymentMethod: &paymentMethod,
}

transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil, nil)

CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
  .transactionCreate(TransactionCreate.builder()
    .amount(1299L)
    .currency("USD")
    .country("US")
    .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
      .method(RedirectPaymentMethodCreateMethod.AFFIRM)
      .country("US")
      .currency("USD")
      .redirectUrl("https://example.com/callback")
      .build()))
    .build())
  .call();

Transaction transaction = transactionResponse.transaction().orElse(null);

$transactionCreate = new TransactionCreate(
  amount: 1299,
  currency: 'USD',
  country: 'US',
  paymentMethod: new RedirectPaymentMethodCreate(
    method: 'affirm',
    country: 'US',
    currency: 'USD',
    redirectUrl: 'https://example.com/callback'
  )
);
$response = $client->transactions->create($transactionCreate);
$transaction = $response->transaction;

transaction: models.Transaction = client.transactions.create(
  amount=1299,
  currency="USD",
  country="US",
  payment_method={
    "method": "affirm",
    "country": "US",
    "currency": "USD",
    "redirect_url": "https://example.com/callback",
  }
)

const transaction = await client.transactions.create({
  amount: 1299,
  currency: "USD",
  country: "US",
  paymentMethod: {
    method: "affirm",
    country: "US",
    currency: "USD",
    redirectUrl: "https://example.com/callback"
  }
})

After the transaction is created, the API response includes a payment_method.approval_url and the status is set to buyer_approval_pending. The approval URL expires after 30 minutes.

{
  "type": "transaction",
  "id": "ea1efdd0-20f9-44d9-9b0b-0a3d71e9b625",
  "payment_method": {
    "type": "payment-method",
    "approval_url": "https://cdn.gr4vy.com/connectors/..."
  },
  "method": "affirm"
}

Redirect the buyer to the approval_url (open in a browser or Webview), where they can complete the payment. Once the buyer approves, the transaction progresses to an authorization_succeeded or capture_succeeded state.

Connection options

Affirm supports the pass through of the following connection options when creating a request. These options allow you to include itinerary details and discount information.

var transaction = await client.Transactions.CreateAsync(
  transactionCreate: new TransactionCreate()
  {
    Amount = 1299,
    Currency = "USD",
    Country = "US",
    PaymentMethod =
      TransactionCreatePaymentMethod.CreateRedirectPaymentMethodCreate(
        new RedirectPaymentMethodCreate()
        {
          Method = "affirm",
          Country = "US",
          Currency = "USD",
          RedirectUrl = "https://example.com/callback",
        }
      ),
    ConnectionOptions = new Dictionary<string, object>()
    {
      ["affirm-affirm"] = new Dictionary<string, object>()
      {
        ["itinerary"] = new Dictionary<string, string>()
        {
          ["type"] = "event",
          ["sku"] = "ABC123",
          ["display_name"] = "Bad Bunny at Petco Park",
          ["venue"] = "Petco Park",
          ["location"] = "100 Park Blvd, San Diego, CA 92101, US",
          ["date_start"] = "2022-12-06T03:00:00.000Z UTC"
        },
        ["discounts"] = new Dictionary<string, object>()
        {
          ["RETURN5"] = new Dictionary<string, object>()
          {
            ["discount_amount"] = 500,
            ["discount_display_name"] = "Returning customer 5% discount"
          },
          ["PRESDAY10"] = new Dictionary<string, object>()
          {
            ["discount_amount"] = 1000,
            ["discount_display_name"] = "President's Day 10% off"
          }
        }
      }
    }
  }
);

amount := int64(1299)
currency := "USD"
country := "US"
method := components.RedirectPaymentMethodCreateMethodAffirm
redirectUrl := "https://example.com/callback"

redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
  Method: method,
  Country: country,
  Currency: currency,
  RedirectURL: redirectUrl,
}
paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)

transactionCreate := components.TransactionCreate{
  Amount:        amount,
  Currency:      currency,
  Country:       &country,
  PaymentMethod: &paymentMethod,
  ConnectionOptions: map[string]any{
    "affirm-affirm": map[string]any{
      "itinerary": map[string]string{
        "type":         "event",
        "sku":          "ABC123",
        "display_name": "Bad Bunny at Petco Park",
        "venue":        "Petco Park",
        "location":     "100 Park Blvd, San Diego, CA 92101, US",
        "date_start":   "2022-12-06T03:00:00.000Z UTC",
      },
      "discounts": map[string]any{
        "RETURN5": map[string]any{
          "discount_amount":       500,
          "discount_display_name": "Returning customer 5% discount",
        },
        "PRESDAY10": map[string]any{
          "discount_amount":       1000,
          "discount_display_name": "President's Day 10% off",
        },
      },
    },
  },
}

transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil, nil)

Map<String, String> itinerary = new HashMap<>();
itinerary.put("type", "event");
itinerary.put("sku", "ABC123");
itinerary.put("display_name", "Bad Bunny at Petco Park");
itinerary.put("venue", "Petco Park");
itinerary.put("location", "100 Park Blvd, San Diego, CA 92101, US");
itinerary.put("date_start", "2022-12-06T03:00:00.000Z UTC");

Map<String, Object> return5 = new HashMap<>();
return5.put("discount_amount", 500);
return5.put("discount_display_name", "Returning customer 5% discount");

Map<String, Object> presday10 = new HashMap<>();
presday10.put("discount_amount", 1000);
presday10.put("discount_display_name", "President's Day 10% off");

Map<String, Object> discounts = new HashMap<>();
discounts.put("RETURN5", return5);
discounts.put("PRESDAY10", presday10);

Map<String, Object> affirmOptions = new HashMap<>();
affirmOptions.put("itinerary", itinerary);
affirmOptions.put("discounts", discounts);

Map<String, Object> connectionOptions = new HashMap<>();
connectionOptions.put("affirm-affirm", affirmOptions);

CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
  .transactionCreate(TransactionCreate.builder()
    .amount(1299L)
    .currency("USD")
    .country("US")
    .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
      .method(RedirectPaymentMethodCreateMethod.AFFIRM)
      .country("US")
      .currency("USD")
      .redirectUrl("https://example.com/callback")
      .build()))
    .connectionOptions(connectionOptions)
    .build())
  .call();

Transaction transaction = transactionResponse.transaction().orElse(null);

$transactionCreate = new TransactionCreate(
  amount: 1299,
  currency: 'USD',
  country: 'US',
  paymentMethod: new RedirectPaymentMethodCreate(
    method: 'affirm',
    country: 'US',
    currency: 'USD',
    redirectUrl: 'https://example.com/callback'
  ),
  connectionOptions: [
    'affirm-affirm' => [
      'itinerary' => [
        'type' => 'event',
        'sku' => 'ABC123',
        'display_name' => 'Bad Bunny at Petco Park',
        'venue' => 'Petco Park',
        'location' => '100 Park Blvd, San Diego, CA 92101, US',
        'date_start' => '2022-12-06T03:00:00.000Z UTC'
      ],
      'discounts' => [
        'RETURN5' => [
          'discount_amount' => 500,
          'discount_display_name' => 'Returning customer 5% discount'
        ],
        'PRESDAY10' => [
          'discount_amount' => 1000,
          'discount_display_name' => "President's Day 10% off"
        ]
      ]
    ]
  ]
);
$response = $client->transactions->create($transactionCreate);
$transaction = $response->transaction;

transaction: models.Transaction = client.transactions.create(
  amount=1299,
  currency="USD",
  country="US",
  payment_method={
    "method": "affirm",
    "country": "US",
    "currency": "USD",
    "redirect_url": "https://example.com/callback",
  },
  connection_options={
    "affirm-affirm": {
      "itinerary": {
        "type": "event",
        "sku": "ABC123",
        "display_name": "Bad Bunny at Petco Park",
        "venue": "Petco Park",
        "location": "100 Park Blvd, San Diego, CA 92101, US",
        "date_start": "2022-12-06T03:00:00.000Z UTC"
      },
      "discounts": {
        "RETURN5": {
          "discount_amount": 500,
          "discount_display_name": "Returning customer 5% discount"
        },
        "PRESDAY10": {
          "discount_amount": 1000,
          "discount_display_name": "President's Day 10% off"
        }
      }
    }
  }
)

const transaction = await client.transactions.create({
  amount: 1299,
  currency: "USD",
  country: "US",
  paymentMethod: {
    method: "affirm",
    country: "US",
    currency: "USD",
    redirectUrl: "https://example.com/callback"
  },
  connectionOptions: {
    "affirm-affirm": {
      itinerary: {
        type: "event",
        sku: "ABC123",
        display_name: "Bad Bunny at Petco Park",
        venue: "Petco Park",
        location: "100 Park Blvd, San Diego, CA 92101, US",
        date_start: "2022-12-06T03:00:00.000Z UTC"
      },
      discounts: {
        RETURN5: {
          discount_amount: 500,
          discount_display_name: "Returning customer 5% discount"
        },
        PRESDAY10: {
          discount_amount: 1000,
          discount_display_name: "President's Day 10% off"
        }
      }
    }
  }
})

​Setup

​Credentials

​Capabilities

​Supported countries

​Supported currencies

​Identifier limitations

​Required fields

​Integration

​Connection options