Online Checkout Tutorial

Payload's flexible API and robust out-of-the-box features make integrating payments into your e-commerce site easy.

How Does it Work

Plug in one of Payload's prebuilt Checkout UI tools
Accept payments securely and compliantly
Safely store payment information for quicker checkout
Use Payload's SDKs to manage customer accounts

Get Started

If you don't already have at least one dedicated Processing Account for your business, you'll need to set one up, otherwise jump to Checkout.

Adding a Processing Account

Add a Processing Account

<script src="https://payload.co/Payload.js"
  pl-client-key="generated_client_token"
  pl-btn-open="processing-account">
</script>

<script>
var pl = Payload('generated_client_token'); // See UI Authentication on how to obtain a client token
new pl.ProcessingAccount()
    .on('account_created', function(evt) {
        console.log(evt.account)
    })
</script>

Response

{}

Every payment needs to be associated with an active Processing Account to process. Processing Accounts specify the pricing and settings for how payments should be processed, including what funding account to transmit the payment to.

Processing Accounts can be added through the dashboard or the full setup process can be integrated into your platform using the Integrated Processing Account Setup toolkit.

To integrate the processing account setup into your app or platform, you can use the Processing Account UI toolkit to capture the details for a new processing account.

Below is an example of the Processing Account form. Click the button to view.

Checkout

Payload Checkout is a UI toolkit for integrating simple payment acceptance into your portal or platform. Below are a few of built-in the benefits of accepting payments using the checkout toolkit.

PCI Compliance
Configurable UI
One-click Checkout

If your platform has recurring customers, you can create Customer accounts and store your customers' payment information and settings for faster checkout.

To create test transactions you can use dummy card numbers as long as they fit a valid format. For some samples:

Card Type	Samples
Visa	`4242 4242 4242 4242`
MasterCard	`5103 2088 7967 2792`
American Express	`3672 005140 64164`
Discover	`6011 9102 7504 5718`

Example

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

Pay Now Button

<form action="/submit_payment" method="POST">
  <script src="https://payload.co/Payload.js"
    pl-client-key="generated_client_token"
    pl-amount="100.00"
    pl-description="Membership">
  </script>
</form>

Step 1) Script Tag

Use the script tag to embed a Pay Now button into your form. This will open an instance of Payload Checkout to accept a new payment.

Step 2) Form Submit

Once a payment is confirmed, a hidden input, <input type="hidden" name="pl_transaction_id" value="{id}">, is added to the form element and then Payload.js automatically submits the form.

Step 3) 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')

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

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

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

On the server side, you must confirm the pl_transaction_id.

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.

JavaScript Interface

Step 1) Open via JavaScript

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

<script>
var pl = Payload('generated_client_token'); // See UI Authentication on how to obtain a client token
var checkout = new pl.Checkout({
    amount: 1000.0,
    description: "Example Payment"
})
</script>

Processed Event

{}

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.

If you enter a payment, you'll see the processed event from the Javascript callback on the right.

Step 2) Watch for Callback

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

When using the JavaScript interface and not Checkout is not embedded within a form, you can watch for the processed callback to receive the transaction id.

Once you receive the transaction id you will need to send that to the server using an asynchronous request or trigger your own form submit.

Step 3) 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')

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

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

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

On the server side, 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.

JavaScript Callbacks

<script>
Payload.on( '.checkout-btn', 'processed', function(evt) {
    console.log('handle event')
})
</script>

Payload Checkout has different JavaScript events that you can watch for. To watch for an event on a Payload Button, you can pass either the element or a css selector as the first parameter.

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

Note: If "Raise Declined Error" is enabled on an API Key, an error event will be triggered if a payment is declined

For a full list of all the ways Payload Checkout can be configured, see the Checkout Configuration section of the documentation.

Customers

You can accept one-time payments without storing customer information, or use the Customer Account object to save customer data for a quicker checkout process.

Step 1) Add a Customer

Create a New Customer

curl "https://api.payload.co/accounts/" \
  -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
  -d email="[email protected]" \
  -d full_name="Matt Perez" \
  -d primary_processing_id="processing_account_id" \
  -d phone_number="1234567890" \
  -d type="customer"

account = pl.Customer.create(
    full_name='Full name',
    email='[email protected]',
    phone_number='(111) 111-1111',
    attrs={
      "custom_attribute": "Custom input"
    },
    primary_processing_id='processing_account_id'
)

const customer = await pl.Customer.create({
    full_name: 'Full name',
    email: '[email protected]',
    phone_number: '(111) 111-1111',
    attrs: {
      "custom_attribute": "Custom input"
    },
    primary_processing_id: 'processing_account_id'
})

Response

{}

Create a new Customer using one of Payload's SDKs. Below is a simple example of a customer onboarding form, with corresponding code snippets on the right.

Step 2) Add Payment Methods

Add Payment Methods

const card = await pl.PaymentMethod.create({
    type: card,
    card: {
      card_number: "numeric",
      expiry: "mm/yy"
    },
    account_id: customer_id
})

card = pl.PaymentMethod.create(
    type='card',
    card={
      'card_number': 'numeric',
      'expiry': 'mm/yy'
    },
    account_id='customer_id'
)

curl https://api.payload.co/payment_methods \
  --header "Content-Type: application/json" \
  -u test_client_key_3bW9JMZtPVDOfFNzwRdfE: \
  -d '{"type":"card","card":{"card_number":"numeric", "expiry":"mm/yy"},"account_id":"customer_id"}'

Response

{}

Secure Input Form Example (Bootstrap 4)

<form id="checkout-form" class="container" pl-form="payment">
    <input type="hidden" pl-input="amount" value="10.00">
    <div class="row pt-2">
        <div class="form-group col-7 px-1">
            <label>Card Number</label>
            <div class="form-control" pl-input="card_number"></div>
        </div>
        <div class="form-group col-3 px-1">
            <label>Expiration</label>
            <div class="form-control" pl-input="expiry"></div>
        </div>
        <div class="form-group col-2 px-1">
            <label>CVC</label>
            <div class="form-control" pl-input="cvc"></div>
        </div>
    </div>
    <div class="row pt-2">
        <button class="btn btn-primary" type="submit">Pay Now</button>
    </div>
</form>

Import Payload

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

Initialize the Form

<script>
  var pl = Payload('generated_client_token'); // See UI Authentication on how to obtain a client token

  var checkout_form = new pl.Form({
      form: $('#checkout-form').get(0)
  })
</script>

Once the Customer account has been created, you can add Payment Methods programmatically, or use Payload's Secure Input feature to securely capture card or bank account information from any HTML form.

Cards

Bank Accounts

One-Click Checkout

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

<script>
  var pl = Payload('generated_client_token'); // See UI Authentication on how to obtain a client token
  var checkout = new pl.Checkout({
    amount: 1000.0,
    description: "Example Payment",
    customer_id: "acct_3bvM06IcMoIklRmC8yfmy"
  })
</script>

Now that you have customers, if your pass a customer_id in when you create your checkout button, their payment information will automatically populate.