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"
        }
      }
    }
  }'

import payload
pl = payload.Session('secret_key_3bW9JMZtPVDOfFNzwRdfE')

@app.route('/form-token', method='post')
def checkout_redirect():

  client_token = pl.ClientToken.create(
    intent=dict(
      payment_form=dict(
        payment=dict(
          amount=100,
          description='Test Payment'
        )
      )
    )
  )

  return jsonify({'client_token': client_token['id']})

require 'payload'
pl = Payload::Session.new('secret_key_3bW9JMZtPVDOfFNzwRdfE')

get '/form-token/' do

  client_token = Payload::ClientToken.create(
    intent: {
      payment_form: {
        payment: {
          amount: 100,
          description: 'Test Payment'
        }
      }
    }
  )

  json({ client_token: client_token['id'] })
end

<?php

$pl_transaction_id = $_GET['pl_transaction_id'];


$clientToken = Payload\ClientToken::create([
  "intent"=>[
    "payment_form"=>[
      "payment": [
        "amount"=>100,
        "description"=>"Test Payment"
      ]
    ]
  ]
]);

header('Content-Type: application/json; charset=utf-8');
echo json_encode(["client_token": $clientToken->id]);
?>

import payload from 'payload-api'
const pl = payload.Session('secret_key_3bW9JMZtPVDOfFNzwRdfE');

app.get('/form-token', (req, res) => {
  const clientToken = pl.ClientToken.create({
    intent: {
      payment_form: {
        payment: {
          amount: 100,
          description: 'Test Payment'
        }
      }
    }
  });

  res.json({ client_token: clientToken.id });
})

using Payload;

[Route("form-token")]
public IHttpActionResult CheckoutRedirect() {
  var pl = new Payload.Session("secret_key_3bW9JMZtPVDOfFNzwRdfE");

  var client_token = await new pl.ClientToken.create(new {
    intent=new {
      payment_form=new {
        new {
          amount=100,
          description="Test Payment"
        }
      }
    }
  });

  return Json(new { client_token = client_token.id });
}

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.

Note: If you're creating a checkout_page intent, redirect to the resulting url instead of passing the id value back to the client.

<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"
      }
    }
  }'

import payload
pl = payload.Session('secret_key_3bW9JMZtPVDOfFNzwRdfE')

@app.route('/checkout-token', method='post')
def checkout_redirect():

  client_token = pl.ClientToken.create(
    intent=dict(
      checkout_plugin=dict(
        amount=100,
        description='Test Payment'
      )
    )
  )

  return jsonify({'client_token': client_token['id']})

require 'payload'
pl = Payload::Session.new('secret_key_3bW9JMZtPVDOfFNzwRdfE')

get '/checkout-token/' do

  client_token = Payload::ClientToken.create(
    intent: {
      checkout_plugin: {
        amount: 100,
        description: 'Test Payment'
      }
    }
  )

  json({ client_token: client_token['id'] })
end

<?php

$pl_transaction_id = $_GET['pl_transaction_id'];


$clientToken = Payload\ClientToken::create([
  "intent"=>[
    "checkout_plugin"=>[
      "amount"=>100,
      "description"=>"Test Payment"
    ]
  ]
]);

header('Content-Type: application/json; charset=utf-8');
echo json_encode(["client_token": $clientToken->id]);
?>

import payload from 'payload-api'
const pl = payload.Session('secret_key_3bW9JMZtPVDOfFNzwRdfE');

app.get('/checkout-token', (req, res) => {
  const clientToken = pl.ClientToken.create({
    intent: {
      checkout_plugin: {
        amount: 100,
        description: 'Test Payment'
      }
    }
  });

  res.json({ client_token: clientToken.id });
})

using Payload;

[Route("checkout-token")]
public IHttpActionResult CheckoutRedirect() {
  var pl = new Payload.Session("secret_key_3bW9JMZtPVDOfFNzwRdfE");

  var client_token = await new pl.ClientToken.create(new {
    intent=new {
      checkout_plugin=new {
        amount=100,
        description="Test Payment"
      }
    }
  });

  return Json(new { client_token = client_token.id });
}

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"
        }
      }
    }
  }'

import payload
pl = payload.Session('secret_key_3bW9JMZtPVDOfFNzwRdfE')

@app.route('/checkout-redirect', method='post')
def checkout_redirect():

  client_token = pl.ClientToken.create(
    intent=dict(
      checkout_page=dict(
        payment=dict(
          amount=100,
          description='Test Payment'
        ),
        redirects=dict(
          completed_url=url_for('/payment-complete'),
          return_url=url_for('/cart'),
        )
      )
    )
  )

  return redirect(client_token.intent['checkout_page']['url'])

require 'payload'
pl = Payload::Session.new('secret_key_3bW9JMZtPVDOfFNzwRdfE')

get '/checkout-redirect/' do

  client_token = Payload::ClientToken.create(
    intent: {
      checkout_page: {
        payment: {
          amount: 100,
          description: 'Test Payment'
        },
        redirects: {
          completed_url: 'http://localhost/payment-complete',
          return_url: 'http://localhost/cart',
        }
      }
    }
  )

  redirect client_token['intent']['checkout_page']['url']
end

<?php

$pl_transaction_id = $_GET['pl_transaction_id'];


$clientToken = Payload\ClientToken::create([
  "intent"=>[
    "checkout_page"=>[
      "payment"=>[
        "amount"=>100,
        "description"=>"Test Payment"
      ],
      "redirects"=>[
        "completed_url"=>"http://localhost/payment-complete",
        "return_url"=>"http://localhost/cart",
      ]
    ]
  ]
]);

header('Location: '.$clientToken->intent["checkout_page"]["url"]);
?>

import payload from 'payload-api'
const pl = payload.Session('secret_key_3bW9JMZtPVDOfFNzwRdfE');

app.get('/checkout-redirect', (req, res) => {
  const clientToken = pl.ClientToken.create({
    intent: {
      checkout_page: {
        payment: {
          amount: 100,
          description: 'Test Payment'
        },
        redirects: {
          completed_url: 'http://localhost/payment-complete',
          return_url: 'http://localhost/cart',
        }
      }
    }
  });

  res.redirect(clientToken.intent.checkout_page.url);
})

using Payload;

public CheckoutRedirect() {
  var pl = new Payload.Session("secret_key_3bW9JMZtPVDOfFNzwRdfE");

  var client_token = await new pl.ClientToken.create(new {
    intent=new {
      checkout_page=new {
        payment=new{
          amount=100,
          description="Test Payment"
        },
        redirects=new {
          completed_url="http://localhost/payment-complete",
          return_url="http://localhost/cart"
        }
      }
    }
  });

  return Redirect(client_token.intent.checkout_page.url);
}

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"
        }
      }
    }
  }'

import payload
pl = payload.Session('secret_key_3bW9JMZtPVDOfFNzwRdfE')

@app.route('/form-token', method='post')
def checkout_redirect():

  client_token = pl.ClientToken.create(
    intent=dict(
      payment_form=dict(
        payment=dict(
          amount=100,
          description='Test Payment'
        )
      )
    )
  )

  return jsonify({'client_token': client_token['id']})

require 'payload'
pl = Payload::Session.new('secret_key_3bW9JMZtPVDOfFNzwRdfE')

get '/form-token/' do

  client_token = Payload::ClientToken.create(
    intent: {
      payment_form: {
        payment: {
          amount: 100,
          description: 'Test Payment'
        }
      }
    }
  )

  json({ client_token: client_token['id'] })
end

<?php

$pl_transaction_id = $_GET['pl_transaction_id'];


$clientToken = Payload\ClientToken::create([
  "intent"=>[
    "payment_form"=>[
      "payment": [
        "amount"=>100,
        "description"=>"Test Payment"
      ]
    ]
  ]
]);

header('Content-Type: application/json; charset=utf-8');
echo json_encode(["client_token": $clientToken->id]);
?>

import payload from 'payload-api'
const pl = payload.Session('secret_key_3bW9JMZtPVDOfFNzwRdfE');

app.get('/form-token', (req, res) => {
  const clientToken = pl.ClientToken.create({
    intent: {
      payment_form: {
        payment: {
          amount: 100,
          description: 'Test Payment'
        }
      }
    }
  });

  res.json({ client_token: clientToken.id });
})

using Payload;

[Route("form-token")]
public IHttpActionResult CheckoutRedirect() {
  var pl = new Payload.Session("secret_key_3bW9JMZtPVDOfFNzwRdfE");

  var client_token = await new pl.ClientToken.create(new {
    intent=new {
      payment_form=new {
        payment=new {
          new {
            amount=100,
            description="Test Payment"
          }
        }
      }
    }
  });

  return Json(new { client_token = client_token.id });
}

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"
        }
      }
    }
  }'

import payload
pl = payload.Session('secret_key_3bW9JMZtPVDOfFNzwRdfE')

@app.route('/form-token', method='post')
def checkout_redirect():

  client_token = pl.ClientToken.create(
    intent=dict(
      payemnt_method=dict(
        payment_method=dict(
          transfer_type='receive-only'
        )
      )
    )
  )

  return jsonify({'client_token': client_token['id']})

require 'payload'
pl = Payload::Session.new('secret_key_3bW9JMZtPVDOfFNzwRdfE')

get '/form-token/' do

  client_token = Payload::ClientToken.create(
    intent: {
      payment_method_form: {
        payment_method: {
          transfer_type: 'receive-only'
        }
      }
    }
  )

  json({ client_token: client_token['id'] })
end

<?php

$pl_transaction_id = $_GET['pl_transaction_id'];


$clientToken = Payload\ClientToken::create([
  "intent"=>[
    "payment_method_form"=>[
      "payment_method": [
        "transfer_type"=>"receive-only"
      ]
    ]
  ]
]);

header('Content-Type: application/json; charset=utf-8');
echo json_encode(["client_token": $clientToken->id]);
?>

import payload from 'payload-api'
const pl = payload.Session('secret_key_3bW9JMZtPVDOfFNzwRdfE');

app.get('/form-token', (req, res) => {
  const clientToken = pl.ClientToken.create({
    intent: {
      payment_method_form: {
        payment_method: {
          transfer_type: 'receive-only'
        }
      }
    }
  });

  res.json({ client_token: clientToken.id });
})

using Payload;

[Route("form-token")]
public IHttpActionResult CheckoutRedirect() {
  var pl = new Payload.Session("secret_key_3bW9JMZtPVDOfFNzwRdfE");

  var client_token = await new pl.ClientToken.create(new {
    intent=new {
      payment_method_form=new {
        payment_method=new {
          new {
            transfer_type="receive-only"
          }
        }
      }
    }
  });

  return Json(new { client_token = client_token.id });
}

Name	Description
`payment_method`	optional Add extra fields to include in the api request.

Authentication

Generating a Client Token with an Intent

Using the Client Token

Intent Options

Options for checkout_plugin intent

Options for checkout_page intent

Options for payment_form intent

Options for payment_method_form intent

Options for `checkout_plugin` intent

Options for `checkout_page` intent

Options for `payment_form` intent

Options for `payment_method_form` intent