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.
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.
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.
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.