Payload.js Checkout

Payload.js exposes a simple drop-in Checkout interface with a robust javascipt API for web and mobile web integrations.

Example

Below is a simple example of Payload Checkout. Click Pay Now to view.

Tutorial

Step 1) Create a Checkout Intent

curl -X POST "https://api.payload.co/access_tokens" \
  -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
  -H 'Content-Type: application/json'
  -d '{
    "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 });
}

To open the checkout plugin you need to first generate the checkout plugin intent. To create a checkout plugin intent create a ClientToken with a nested checkout_plugin intent object. See the Intent Options section below for a full list of available parameters.

Once the client token is generated, return that to the client and pass that the token value Payload function. Now you can open the checkout plugin as shown in Step 2.

Step 2) Open Checkout

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

<script>
Payload('generated_client_token');

const checkout = new Payload.Checkout({
    amount: 1000.0,
    description: "Example Payment"
})
</script>

Payload Checkout can be opened using the javascript interface by creating a new instance of Payload.Checkout, as seen in the example.

You can have Payload Checkout automatically submit a form after a successful payment by passing the form element as the form parameter when creating the checkout instance.

Step 3) Watch for event callback or form submit

<script>
checkout.on('success', function(evt) {
    $.post('/submit_payment',
        { pl_transaction_id: evt.transaction_id })
})
</script>

If Checkout is not embedded within a form, you can watch for the success event to receive the transaction id. Once you receive the transaction id, store that for future reference.

If Checkout is embedded in a form, once a payment is processed a hidden input with name pl_transaction_id is added to the form element and then, if autosubmit is enabled, Payload.js automatically submits the form.

Step 4) Server Confirmation

pl_transaction_id = 'txn_19QsDurdSxJ0gVNzOcQSlew3D'
curl "https://api.payload.co/transactions/$pl_transaction_id" \
    -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
    -X PUT \
    -d status=processed

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

@app.route('/submit_payment', method='post')
def post_transaction(pl_transaction_id):
    pl.Transaction(id=pl_transaction_id)\
        .update(status='processed')

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

post '/submit_payment/' do
  pl_transaction_id = params[:pl_transaction_id]

  transaction = Payload::Payment.
    get(pl_transaction_id).
    update(
      status: 'processed'
    )
end

<?php
Payload\Payload::$api_key = 'secret_key_3bW9JMZtPVDOfFNzwRdfE';

$pl_transaction_id = $_GET['pl_transaction_id'];


$transaction = Payload\Transaction::filter_by(
        pl::attr()->id->eq(pl_transaction_id)
    )->update(array( 'status' => 'processed' ));
);
?>

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

app.post('/submit_payment', (req, res) => {
    const pl_transaction_id = req.body.pl_transaction_id
    pl.Payment({ id: pl_transaction_id })
        .update({ status: 'processed' })
        .then(function() {
            res.send('Payment Successful!')
        })
})

using Payload;
var pl = new Payload.Session("secret_key_3bW9JMZtPVDOfFNzwRdfE");

string pl_transaction_id = "txn_19QsDurdSxJ0gVNzOcQSlew3D";

var payment = await new pl.Payment(new {
    id = pl_transaction_id
  })
  .UpdateAsync(new { status = "processed" });

On the server side, unless you've disabled "Two-step authorization" in your API Key settings, you must confirm the pl_transaction_id using the transactions api.

The transaction has only been authorized at this point. To confirm the transaction you need to update the status from authorized to processed as seen in the example.

Events

<script>
checkout.on('authorized', function(evt) {
    console.log('handle event')
})
</script>

Payload Checkout has a few different events that you can watch for. To watch for an event, use the on method on the Checkout object. The on method accepts an event name and an event function as the parameters.

Event	Description
`loaded`	Event triggered after the form has been successfully completed
`success`	Event triggered after a payment has been initialized successfully
`processed`	Event triggered after a payment has been processed successfully
`authorized`	Event triggered after a payment has been authorized successfully
`declined`	Event triggered if a payment attempt was declined *
`closed`	Event triggered after the form has been closed

Note:"Raise Declined Error" must be disabled on an API Key to trigger a declined event

Custom Styling

<script>
const checkout = new Payload.Checkout({
    amount: 1000.0,
    description: "Example Payment",
    style: {
        'default': {
            primaryColor: '#ff00ff',
            backgroundColor: '#ffffff',
            color: '#000000',
            input: {
                borderColor: '#efefef',
                boxShadow: 'none',
            },
            header: {
                backgroundColor: '#eeccff',
            },
            button: {
                boxShadow: 'none',
            }
        }
    }
})
</script>

The checkout plugin accepts a style option. The default style accepts the following options:

CSS Style	Description
`primaryColor`	Hex color code to override the primary color.
`backgroundColor`	Hex color code to override the plugin background.
`color`	Hex color code to override the standard text color.
`input.borderColor`	Hex color code to override the input border color.
`input.boxShadow`	Override the input box shadow css rule.
`header.backgroundColor`	Hex color code to override the modal header background color.
`header.color`	Hex color code to override the modal header text color.
`button.boxShadow`	Override the button shadow css rule.
`button.color`	Hex color code to override the button text color.

Intent Options

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.

Checkout Configuration

Attributes	Description
`container`	An html element to embed the interface instead of a popup.
`form`	If present, following a successful payment the form will be submitted with the `pl_transaction_id` parameter.
`autosubmit`	Set to `false` to disable automatic form submit.