Checkout

Conversion-optimised payment forms, hosted on Javelin that allow you to capture payments, save cards and handle authentications.

Your Javelin integration starts here

Javelin Checkout's payment links are an easy way of accepting payments, using hosted pages on Javelin. By using our Checkout, we generate the payment links, so you don't need to implement the checkout UI, or handle authentication flows.

• Our payment page is optimised for conversion.

• Match your brand - Javelin payments will implement custom hosted card saving pages.

• Support authentication flows like Dynamic 3D Secure to reduce fraud - and meet European regulations.

Create payment links

You can create payment links using POST /link endpoint.

Here is an example API request to create a payment link.

curl --location \
  --request POST 'https://test.javelinhq.com/api/link' \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/vnd.xyzpay.v1+json' \
  --data-urlencode 'company_id=44' \
  --data-urlencode 'reference=REF_ABCDEF' \
  --data-urlencode 'shopper_reference=MY_USER_1234' \
  --data-urlencode 'amount=10' \
  --data-urlencode 'currency=EUR' \
  --data-urlencode 'statement_descriptor=My statement descriptor' \
  --data-urlencode 'shopper_first_name=John' \
  --data-urlencode 'shopper_last_name=Doe' \
  --data-urlencode 'shopper_locale=en_US' \
  --data-urlencode 'return_url=https://your_return.url'

This API call will return a response as this

{
    "data": {
        "id": 39,
        "url": "http://s.txtpay.xyz/qrDWM",
        "status": "created",
        "auto_capture": false,
        "amount": 10,
        "currency": "EUR"
    }
}

You now need to redirect the shopper to the url.

Finding out the result of a payment link

Once the shopper has completed the payment, s/he will be redirected back to the return_url you provided in the POST /link endpoint call. The return_url will also contain a pt_id query parameter which is the id of a PendingTransaction , which will tell you the result of the transaction made by the payment link. So, in the example the shopper will be redirected to -https://your_return.url?pt_id=PT_5f689c6154b0e

In order to see the details of a PendingTransaction you can use -GET /pendingTransaction/{pendingTransactionId} endpoint where pendingTransactionId is pt_id in the query in the return_url.

curl --location \
    --request GET 'https://test.javelinhq.com/api/pendingTransaction/PT_5f689c6154b0e' \
    --header 'x-api-key: <YOUR_API_KEY>' \
    --header 'Accept: application/vnd.xyzpay.v1+json'

This call will return the result of a PendingTransaction

{
    "data": {
        "id": "PT_5f689c6154b0e",
        "status": "succeeded",
        "transaction_id": 3417,
        "card_id": null,
        "error": null,
        "created_at": "2020-09-21T12:28:17.000000Z",
        "updated_at": "2020-09-21T12:28:18.000000Z",
        "card": null,
        "transaction": {
            "data": {
                "id": 3417,
                "risk_score": 50,
                "last4": "1142",
                "cardholder_name": "john doe",
                "expiry_date": "3/2030",
                "threeDSVersion": null,
                "postal_code": null,
                "shopper_reference": "MY_USER_1234",
                "shopper_phone_country": null,
                "shopper_phone": null,
                "shopper_email": null,
                "shopper_name": "Can Gelis",
                "payment_method": "visa",
                "merchant_reference": "LINK_5f689c6154b0e",
                "status": "authorized",
                "external_id": "852600691297307G",
                "amount": 10,
                "refunded_amount": 0,
                "net_amount": 0,
                "currency": "EUR",
                "fail_reason": null,
                "metadata": {
                    "company": "sample",
                    "link_id": 39,
                    "type": "xyzpay_web_pay",
                    "booking_no": null,
                    "shopper_name": "John Doe"
                },
                "settled_at": null
            }
        }
    }
}

PendingTransaction's status will show you the result of the payment link. PendingTransaction also has the transaction property, which is the actual Transaction object, containing the transaction details carried out by the shopper via the Checkout link.

Auto-capturing the payment links

You can either only pre-authorise the payment, or you can auto-capture it immediately once the payment has been created. In order to create an auto-captured payment link, you can provide auto_capture=1 in the POST /link call.

curl --location \
  --request POST 'https://staging-dashboard.xyzpay.co.uk/api/link' \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/vnd.xyzpay.v1+json' \
  --data-urlencode 'company_id=44' \
  --data-urlencode 'reference=REF_ABCDEF' \
  --data-urlencode 'shopper_reference=MY_USER_1234' \
  --data-urlencode 'amount=10' \
  --data-urlencode 'currency=EUR' \
  --data-urlencode 'statement_descriptor=My statement descriptor' \
  --data-urlencode 'shopper_first_name=John' \
  --data-urlencode 'shopper_last_name=Doe' \
  --data-urlencode 'shopper_locale=en_US' \
  --data-urlencode 'return_url=https://your_return.url'
  --data-urlencode 'auto_capture=1'

Once the payment is made by the shopper, the transaction object will have status of settled.

{
    "data": {
        "id": "PT_5f689c6154b0e",
        "status": "succeeded",
        "transaction_id": 3417,
        "card_id": null,
        "error": null,
        "created_at": "2020-09-21T12:28:17.000000Z",
        "updated_at": "2020-09-21T12:28:18.000000Z",
        "card": null,
        "transaction": {
            "data": {
                "id": 3417,
                "risk_score": 50,
                "last4": "1142",
                "cardholder_name": "john doe",
                "expiry_date": "3/2030",
                "threeDSVersion": null,
                "postal_code": null,
                "shopper_reference": "MY_USER_1234",
                "shopper_phone_country": null,
                "shopper_phone": null,
                "shopper_email": null,
                "shopper_name": "Can Gelis",
                "payment_method": "visa",
                "merchant_reference": "LINK_5f689c6154b0e",
                "status": "settled",
                "external_id": "852600691297307G",
                "amount": 10,
                "refunded_amount": 0,
                "net_amount": 0,
                "currency": "EUR",
                "fail_reason": null,
                "metadata": {
                    "company": "sample",
                    "link_id": 39,
                    "type": "xyzpay_web_pay",
                    "booking_no": null,
                    "shopper_name": "John Doe"
                },
                "settled_at": null
            }
        }
    }
}

Capturing the pre-authorised payment links

POST /transaction/{transactionId}/capture endpoint can be used for capturing a pre-authorised payment.

curl --location --request POST 'https://test.javelinhq.com/api/transaction/3417/capture' \
    --header 'Accept: application/vnd.xyzpay.v1+json' \
    --header 'x-api-key: <YOUR_API_KEY>' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'amount=100'

transactionId in POST /transaction/{transactionId}/capture is the id of a transaction rather than pending transaction.

Card Saving

You can also save the cards in the same process as carrying out the transaction. Once the payment has succeeded, the shopper's card is saved and PendingTransaction will contain a card property.

In order to save the cards along with the payment transaction, provide recurring=1 in the link creation.

Example link create request for card saving

curl --location \
  --request POST 'https://test.javelinhq.com/api/link' \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/vnd.xyzpay.v1+json' \
  --data-urlencode 'company_id=44' \
  --data-urlencode 'reference=REF_ABCDEF' \
  --data-urlencode 'shopper_reference=MY_USER_1234' \
  --data-urlencode 'amount=10' \
  --data-urlencode 'currency=EUR' \
  --data-urlencode 'statement_descriptor=My statement descriptor' \
  --data-urlencode 'shopper_first_name=John' \
  --data-urlencode 'shopper_last_name=Doe' \
  --data-urlencode 'shopper_locale=en_US' \
  --data-urlencode 'return_url=https://your_return.url'
  --data-urlencode 'recurring=1'

You can use amount=0 in order to save the card without charging the shopper.

and here is an example GET /pendingTransaction/{pendingTransactionId} response for a link that has recurring=1

{
    "data": {
        "id": "LINK_5f689c6154b0e",
        "status": "succeeded",
        "transaction_id": 3417,
        "card_id": "CARD_5f689c62a2523",
        "error": null,
        "created_at": "2020-09-21T12:28:17.000000Z",
        "updated_at": "2020-09-21T12:28:18.000000Z",
        "card": {
            "data": {
                "id": "CARD_5f689c62a2523",
                "external_id": "8415998118341724",
                "shopper_reference": "MY_USER_1234",
                "last4": "1142",
                "alias": "H030757487506793",
                "authorisation_id": "852600691297307G",
                "transaction_id": 3417,
                "brand": "visa",
                "card_holder_name": "John Doe",
                "exp_month": "3",
                "exp_year": "2030",
                "is_business": 0,
                "created_at": "2020-09-21T12:28:18.000000Z"
            }
        },
        "transaction": {
            "data": {
                "id": 3417,
                "risk_score": 50,
                "last4": "1142",
                "cardholder_name": "John Doe",
                "expiry_date": "3/2030",
                "threeDSVersion": null,
                "postal_code": null,
                "shopper_reference": "MY_USER_1234",
                "shopper_phone_country": null,
                "shopper_phone": null,
                "shopper_email": null,
                "shopper_name": "Can Gelis",
                "payment_method": "visa",
                "merchant_reference": "LINK_5f689c6154b0e",
                "status": "authorized",
                "external_id": "852600691297307G",
                "amount": 10,
                "refunded_amount": 0,
                "net_amount": 0,
                "currency": "EUR",
                "fail_reason": null,
                "metadata": {
                    "company": "sample",
                    "link_id": 39,
                    "type": "xyzpay_web_pay",
                    "booking_no": null,
                    "shopper_name": "John Doe"
                },
                "settled_at": null
            }
        }
    }
}

Need help? Contact Javelin support team