Checkout Page

Create single-use customizable checkout pages to accept payments at checkout.

Step 1) Create a Checkout Link

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);
}

To generate the checkout page, create a ClientToken with a nested checkout_page intent. At a minimum the checkout page intent requires an amount, description, and a completed and return redirect url. See the Checkout Configuration section below for a full list of available parameters.

Once the client token is generated, you can redirect the customer to the checkout page url found in the response. The customer will be able to submit their payment, which will then redirect them to the completed_url if the payment is successful or they can return back to the order page or cart based on the return_url.

If the payment is successful, you'll need to confirm the payment on the back-end. See Step 2 below.

Step 2) Payment Confirmation

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

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

@app.route('/payment-complete', method='get')
def post_transaction():
    pl.Transaction(id=request.args.get('pl_transaction_id')\
        .update(status='processed')

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

get '/payment-complete/' 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.get('/submit_payment', (req, res) => {
    const pl_transaction_id = req.query.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.

Checkout Configuration

Name	Description
`payment` required	Preset values for the resulting Payment object
`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` default: false	Use true or false to specify whether billing address fields are displayed. Default is false.
`enable_mobile_wallets` bool	Enable Google/Apple Pay
`show_disclosure` bool	Show disclosure