Initiating Payments

Simple Card Payments

curl "https://api.payload.co/transactions" \
    -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
    -d "amount=100" \
    -d "type=payment" \
    -d "payment_method[type]=card" \
    -d "payment_method[card][card_number]=4242 4242 4242 4242" \
    -d "payment_method[card][expiry]=12/25"

payment = pl.Payment.create(
    amount=100.0,
    payment_method=pl.Card(
        card_number='4242 4242 4242 4242',
        expiry='12/25'
    )
)

<?php
$payment = Payload\Transaction::create(array(
    'amount'=> 100.0,
    'type'=> 'payment',
    'payment_method' =>new Payload\PaymentMethod(array(
        'type'=> 'card',
        'card'=> array('card_number'=>'4242 4242 4242 4242', 'expiry'=>'12/25')
    )),
));
?>

const payment = await pl.Payment.create({
    amount: 100.0,
    payment_method: pl.Card({
        card_number: '4242 4242 4242 4242',
        expiry: '12/25'
    })
})

var payment = await pl.Payment.CreateAsync(new {
    amount = 100.0,
    payment_method = new pl.Card(new {
        card_number = "4242 4242 4242 4242",
        expiry = "12/25"
    })
});

payment = Payload::Payment.create(
    amount: 100.0,
    payment_method: Payload::Card.new(
        card_number: '4242 4242 4242 4242',
        expiry: '12/25'
    )
)

Processing card payments at a minimum requires a card number and expiration date but typically it's recommended to also provide the CVV, billing zipcode, and the cardholder's name for validation.

Simple Bank Payments

curl "https://api.payload.co/transactions" \
    -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
    -d "amount=100" \
    -d "type=payment" \
    -d "payment_method[type]=bank_account" \
    -d "payment_method[bank_account][account_number]=1234567890" \
    -d "payment_method[bank_account][routing_number]=021000021" \
    -d "payment_method[bank_account][account_type]=checking"

payment = pl.Payment.create(
    amount=100.0,
    payment_method=pl.BankAccount(
        account_number='1234567890',
        routing_number='021000021',
        account_type='checking'
    )
)

<?php
    $payment = Payload\Transaction::create(array(
        'amount'=>100.0,
        'type' => 'payment',
        'payment_method'=>new Payload\PaymentMethod(array(
            'type'=> 'bank_account',
            'bank_account'=>array(
                'account_number'=>'1234567890',
                'routing_number'=> '021000021',
                'account_type' => 'checking'
                )
        ))
    ));
?>

const payment = await pl.Payment.create({
    amount: 100.0,
    payment_method: pl.BankAccount({
        account_number: '1234567890',
        routing_number: '021000021',
        account_type: 'checking'
    })
})

var payment = await pl.Payment.CreateAsync(new {
    amount = 100.0,
    payment_method = new pl.BankAccount(new {
        account_number = "1234567890",
        routing_number = "021000021",
        account_type = "checking"
    })
});

payment = Payload::Payment.create(
    amount: 100.0,
    payment_method: Payload::BankAccount.new(
        account_number: '1234567890',
        routing_number: '021000021',
        account_type: 'checking'
    )
)

Processing bank account payments requires the customer's account number, routing number, and account type. This will attempt to process the payment with the customer's bank through either ACH, PAD, or RTP networks depending on the account settings and currency.

Canadian Bank Payments

On the check, the routing number is usually BBBBB-III (I is the institution, B is the branch or bank transit code). To translate this to an EFT routing number, you would format it as 0IIIBBBBB. See also Routing numbers (Canada)

Test Payments

We provide an extensive list of test payment accounts in the Test Cards and Test Bank Accounts sections.

One-Time Payments

Some cases may require a one-time payment without saving a payment method. To enable this behavior set the keep_active flag to false on the Payment Method object.

Two-step Processing

curl "https://api.payload.co/transactions" \
    -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
    -d "amount=100" \
    -d "type=payment" \
    -d "status=authorized" \
    -d "payment_method[type]=card" \
    -d "payment_method[card][card_number]=4242 4242 4242 4242" \
    -d "payment_method[card][expiry]=12/25"

curl -X PUT "https://api.payload.co/transactions/<transaction_id>" \
    -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
    -d "status=processed"

payment = pl.Payment.create(
    amount=100.0,
    status='authorized',
    payment_method=pl.Card(
        card_number='4242 4242 4242 4242',
        expiry='12/25'
    )
)

payment.update(status='processed')

<?php
$payment = Payload\Transaction::create(array(
    'amount'=> 100.0,
    'type'=> 'payment',
    'status'=>'authorized',
    'payment_method' =>new Payload\PaymentMethod(array(
        'type'=> 'card',
        'card'=> array('card_number'=>'4242 4242 4242 4242', 'expiry'=>'12/25')
    )),
));

$payment->update(['status'=>'processed'])
?>

let payment = await pl.Payment.create({
    amount: 100.0,
    status: 'authorized',
    payment_method: pl.Card({
        card_number: '4242 4242 4242 4242',
        expiry: '12/25'
    })
})
payment = await payment.update({status: 'processed'})

var payment = await pl.Payment.CreateAsync(new {
    amount = 100.0,
    status = "authorized",
    payment_method = new pl.Card(new {
        card_number = "4242 4242 4242 4242",
        expiry = "12/25"
    })
});

await payment.UpdateAsync(new { status = "processed" });

payment = Payload::Payment.create(
    amount: 100.0,
    status: 'authorized',
    payment_method: Payload::Card.new(
        card_number: '4242 4242 4242 4242',
        expiry: '12/25'
    )
)

payment.update(status: 'processed')

When initiating a payment, by default there are two steps to complete the transaction. The transaction status will be set to authorized on the initial request but the funds will not be processed immediately. When the transaction is finalized, an update can be made to change the status from authorized to processed. Once the payment has been updated from authorized to processed, the funds will begin processing and be debited from the account.

By default "Two Step Verify Processing" is turned on. This can be changed in the Payload dashboard under Settings -> API Keys. If the Two Step Verify Processing setting is turned off, when initiating a payment, if that payment is successful the transaction status will return as processed. This means that the transaction was both successfully authorized and funds will be processed immediately, debiting them from the specified account.

Setting the initial status to authorized is supported by both the Secure Input and Checkout ui elements.