Skip to main content

Merchant Help

 

Affirm Merchant Help

Generate Checkout Session Token

Using checkout session tokens

A checkout session token is generated server-side, so that the checkout initiation on the client-side does not involve any handling of sensitive customer information (PII).

Once a user's checkout data is altered, a new session token must be generated.

The checkout session token request can result in several possible errors, which should be handled by your server and then presented to the user on the front-end.

Request format

Method: POST
Authentication: Basic Auth, Base64 ASCII encoded public:private keypair
Body: JSON format checkout data

Response format

Body: JSON

Checkout data

{
  "merchant":{
    "name": "Your Customer-Facing Merchant Name"
   },
  "shipping":{
    "name":{
      "full":"John Doe"
    },
    "address":{
      "line1":"325 Pacific Ave",
      "city":"San Francisco",
      "state":"CA",
      "zipcode":"94112",
      "country":"USA"
    }
  },
  "billing":{
    "name":{
      "full":"John Doe"
    },
    "address":{
      "line1":"325 Pacific Ave",
      "city":"San Francisco",
      "state":"CA",
      "zipcode":"94112",
      "country":"USA"
    }
  },
  "items": [{
    "display_name":         "Awesome Pants",
    "sku":                  "ABC-123",
    "unit_price":           1999,
    "qty":                  3,
    "item_image_url":       "http://merchantsite.com/images/awesome-pants.jpg",
    "item_url":             "http://merchantsite.com/products/awesome-pants.html"
  }],

  "discounts": {
    "RETURN5": {
      "discount_amount":    500,
      "discount_display_name": "Returning customer 5% discount"
    },
    "PRESDAY10": {
      "discount_amount":    1000,
      "discount_display_name": "President's Day 10% off"
    }
  },

  "metadata": {
    "shipping_type":        "UPS Ground"
  },

  "order_id":               "JKLMO4321",

  "shipping_amount":        1000,
  "tax_amount":             500,
  "total":                  6997
}
 
merchant
optional object. If you have multiple sites operating under a single Affirm account, you can override the external company/brand name that the customer sees using 'name'. This affects all references to your company name in the Affirm UI. 
billing
optional object.  Customer contact information.
shipping
required object. Customer contact information.
items
required list. A list of item objects.
discounts
optional hash. A hash of coupon code to discount objects.
tax_amount
required integer. The total tax amount computed after all discounts have been applied; Defaults to 0.
shipping_amount
required integer. The total shipping amount; Defaults to 0.
total
required integer. The total amount of the checkout. This determines the total amount charged to the user.
metadata
optional object. A hash of keys to values for any metadata to be passed into checkout and stored.
order_id
optional string. Your internal order id. This is stored for your own future reference.

Error response format

{
  "field": "object.field", 
  "message": "Some customer facing message.", 
  "code": "invalid_field", 
  "type": "invalid_request",
  "status_code": 40x|50x
}
field
string. Specific arameter/field associated with the returned error.
message
string. User-facing error message to be displayed on the front-end.
code
enum. Error code associated with this type of error.
type
string. Generic issue description.
status_code
integer. HTTP status code result for this request.

Example request

curl https://sandbox.affirm.com/api/v2/checkout/session \
     --verbose \
     -X POST \
     -u "ARQBLCL7NAMBTZ7F:RkHBmVSP5ayC2rCUujwhArpGWPxpuTtv" \
     -H "Content-Type: application/json"\
     -d '{"merchant": {"name":"Your Customer Facing Merchant Name"},"items": [{"display_name": "Great product","item_url": "http://www.google.com","item_image_url": "","qty": 2,"sku": "ABC123","unit_price": 10000}],"shipping": {"address": {"city": "San Francisco","line1": "633 Folsom Street","state": "CA","zipcode": "94107"},"name":{"full":"Ben Mo"},"phone_number":"9253232323"},"billing": {"address": {"city": "San Francisco","line1": "633 Folsom Street","state": "CA","zipcode": "94107"},"email":"benmoo@gmail.com","name":{"full":"Ben Mo"},"phone_number":"9253232323"},"total": 10000}'

Example success response

 

{
  "checkout_session_token": "ABCBLCL7NAMBTZDZ"
  "created": "2016-04-05T15:37:44.286033Z"
}
checkout_session_token
string. This event is triggered when the user successfully completes the Affirm checkout flow. The event data contains the virtual card token. This token will then be subsequently exchanged for the virtual card details via server-side API.
created
timestamp. This event is triggere

 

Example error response

 

{
  "field": "billing.name", 
  "message": "Please verify your name.", 
  "code": "invalid_field", 
  "type": "invalid_request",
  "status_code": 400
}
field
string. Specific arameter/field associated with the returned error.
message
string. User-facing error message to be displayed on the front-end.
code
enum. Error code associated with this type of error.
type
string. Generic issue description.
status_code
integer. HTTP status code result for this request.

 

Error Response Fields 

Edit section

Field R/O/C Type Description
field R String Field containing an incorrect or invalid value.
message R String Friendly message that describes the issue.
code R String Short code referencing the specific error.
type R String Type of error being returned.
status_code R String HTTP Status Code that was returned.

Possible code values 

Edit section

The list below contains all of the possible code values that can be returned by Affirm.

auth-declined
Charge authorization hold declined.
capture-greater-instrument
Charges on this instrument cannot be captured for more than the authorization hold amount.
capture-unequal-instrument
Charges on this instrument cannot be captured for an amount unequal to authorization hold amount.
capture-voided
Cannot capture voided charge.
partial-capture-instrument
Charges on this instrument cannot be partially captured.
refund-exceeded
Max refund amount exceeded.
refund-uncaptured
Cannot refund a charge that has not been captured.
refund-voided
Cannot refund voided charge.
capture-declined
Charge capture declined.
capture-limit-exceeded
Max capture amount on charge exceeded.
expired-authorization
Cannot capture expired charge authorization hold.
refund-expired
Charges on this instrument must be refunded within N days of capture.
financial-product-invalid
Please provide a valid financial product key.
invalid_field
An input field resulted in invalid request.
public-api-key-not-specified
Please provide a public API key.
public-api-key-invalid
Please provide a valid public API key.
public-api-key-wrong-environment
Please provide a live public API key when not using the sandbox environment.
public-api-key-inactive
Please provide an active public API key.
api-key-pair-not-specified
Please provide a API key pair.
private-api-key-invalid
Please provide a valid private API key.
api-key-pair-wrong-environment
Please provide a live API key pair when not using the sandbox environment.
api-key-pair-inactive
Please provide an active API key pair.
not_found
The resource(s) specified in the request could not be found.

Possible type values 

Edit section

The list below contains all of the possible type values that can be returned by Affirm.

invalid-request
A generic error that indicates request inputs were invalid.
unauthorized
API keys were invalid.

Possible status_code values 

Edit section

The list below contains all of the possible status_code values that can be returned by Affirm.

400
Request fields resulted in an error.
401
Authorization was unsuccessful.
404
The requested resource(s) could not be found.
50x
An internal server issue resulted in an error.