Handling Results

Once a form submit is triggered, a request is sent to Payload with only the data from the secure inputs within the form. If the request to payload is successful, the form submit proceeds as normal. If the request is unsuccessful, the invalid inputs are shown as invalid.

Successful Result

If the request to Payload is successful, a hidden element containing the new object's id will be embedded into the form. If the pl-form attribute is set to payment then an input with the name pl_transaction_id will be added to the form. If the pl-form attribute is set to payment_method then an input with the name pl_payment_method_id will be added to the form.

<input type="hidden" name="pl_transaction_id" value="<id of new payment>">

Once this input has been added to the form, a form submit is triggered.

Override Form Submit

<script>
const checkout = new Payload.Form({
    form: document.getElementById('checkout-form'),
    autosubmit: false
}).on('success', function(evt) {
    /*handle response*/
})
</script>

If you want to handle the form in a different way and don't want it to be submitted, you can use the autosubmit: false option when initializing the form. You can watch for the JavaScript events and handle the results in another manner.

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('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" });

For payments initiated with Secure Inputs, unless you've disabled "Two-step authorization" in your API Key settings, 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.

Invalid Input

<script>
const checkout = new Payload.Form(document.getElementById('checkout-form'))
    .on('invalid',function(evt) {
        /*handle invalid data*/
        $(evt.target).css({background:'red'})
        alert(evt.message)
    })
    .on('valid',function(evt) {
        /*revert to a valid input*/
        $(evt.target).css({background:'white'})
    })
    .on('error',function(evt) {
        /*handle bad request*/
    })
</script>

If the request to Payload is invalid, the pl-invalid css class will be applied to any invalid inputs. Note: the default invalid css class name can be changed

There is also an invalid and an error event that can be used for custom error handling. The invalid event will only fire if any of the input fields contain invalid values. The error event will trigger any error response from the API request. Please see the errors section for more information on possible error responses.

Declined Payment

<script>
const checkout = new Payload.Form(document.getElementById('checkout-form'))
    .on('declined',function(evt) {
        /*handle declined payment*/
        console.log(evt.status_code)
        alert(evt.message)
    })
</script>

If the payment request to Payload results in a decline, the declined event will fire with a message attribute describing the reason and the decline status code.