Shell Python Node PHP C# Ruby

Authentication

Generate a client token with intent on the server side

curl -X POST "https://api.payload.com/access_tokens" \
  -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "client",
    "intent": {
      "payment_form": {
        "payemnt": {
          "amount": 100,
          "description": "Test Payment"
        }
      }
    }
  }'

Generating a Client Token with an Intent

An ephemeral client token with an intent is required for authentication when using a client side ui element. To create a new token use the ClientToken object from one of our server side libraries or use the endpoint /access_tokens with the body {"type": "client"} and a nested intent object.

There's a few different types of intents depending on what ui element and request type you're trying to make. Below is a table of the different intent types and what they're used for.

Name Description
checkout_plugin Use with the embedded checkout plugin.
checkout_page Use with the checkout page redirect.
processing_account_plugin Use with the processing account plugin.
payment_form Use with secure input payment forms.
payment_method_form Use with secure input payment method forms.
oauth_client_token Use with oauth connect.

Using the Client Token

Once the ClientToken is generated, pass the resulting id value back to the client. You can then initialize Payload.js with the value as shown below.

<script src="https://payload.com/Payload.js"></script>

<script>
fetch('/gen_token', {method: 'POST'})
  .then(token=>Payload(token))
</script>

Intent Options


Options for checkout_plugin intent

curl -X POST "https://api.payload.com/access_tokens" \
  -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "client",
    "intent": {
      "checkout_plugin": {
        "amount": 100,
        "description": "Test Payment"
      }
    }
  }'
Name Description
amount
required without invoice id
The payment amount.
description
required
A description of the payment.
amount_editable
optional
Allow custom amounts.
processing_id
optional
The processing account id for the payment.
customer_id
optional
The customer's account id.
card_payments
default: true
Specifies if payments via card are accepted.
bank_account_payments
default: false
Specifies if payments via bank account are accepted.
order_number
optional
Provice a custom order number for the payment.
billing_address
default: false
Use true or false to specify whether billing address fields are displayed. Default is false.
invoice_id
optional
To tie the resulting payment to an invoice, pass the invoice id value.
auto_billing_toggle
default: false
Adds an option to allow the customer to set the payment method as the billing default.
keep_active_toggle
default: false
Adds an option to allow the customer to store the payment method for future use.
payment_method_preview
default: false
Set to true to show a graphical preview of the payment method above the checkout form.
attrs
optional
Transaction custom attributes JSON object. Example: {"example":"data"}
status
optional
Set to authorized for a pre-auth payment.
conv_fee
optional
Use true or false to specify whether the fee should be charged as a convenience.

Options for checkout_page intent

curl -X POST "https://api.payload.com/access_tokens" \
  -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "client",
    "intent": {
      "checkout_page": {
        "payment": {
          "amount": 100,
          "description": "Test Payment"
        },
        "redirects": {
          "completed_url": "http://localhost/payment-complete",
          "return_url": "http://localhost/cart"
        }
      }
    }
  }'
Name Description
payment
required
Preset values for the resulting payment.
card_payments
default: true
Specifies if payments via card are accepted.
bank_account_payments
default: false
Specifies if payments via bank account are accepted.
billing_address Use true or false to specify whether billing address fields are displayed. Default is false.

Options for payment_form intent

curl -X POST "https://api.payload.com/access_tokens" \
  -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "client
    "intent": {
      "payment_form": {
        "payemnt": {
          "amount": 100,
          "description": "Test Payment"
        }
      }
    }
  }'
Name Description
payment optional Add extra fields to include in the api request.

Options for payment_method_form intent

curl -X POST "https://api.payload.com/access_tokens" \
  -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "client
    "intent": {
      "payment_method_form": {
        "payemnt_method": {
          "transfer_type": "receive-only"
        }
      }
    }
  }'
Name Description
payment_method optional Add extra fields to include in the api request.