Transaction API

The transaction API is used to process your online card payments.

Create a transaction

The payment transaction can be created using POST /transaction endpoint. To create a transaction you must first save the card. Please review our Checkout documentation to follow the steps for card saving.

Example API Request

curl --location --request POST 'https://test.javelinhq.com/api/transaction' \
    --header 'Accept: application/vnd.xyzpay.v1+json' \
    --header 'x-api-key: <YOUR_API_KEY>' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'company_id=44' \
    --data-urlencode 'amount=1000' \
    --data-urlencode 'currency=EUR' \
    --data-urlencode 'channel=web' \
    --data-urlencode 'card_id=CARD_5f649e4675e63' \
    --data-urlencode 'shopper_locale=en_US' \
    --data-urlencode 'return_url=http://your_return.url' \
    --data-urlencode 'shopper_first_name=John' \
    --data-urlencode 'shopper_last_name=Doe' \
    --data-urlencode 'shopper_email=[e-mail]' \
    --data-urlencode 'shopper_phone=[phone]'

The POST /transaction endpoint will return an PendingTransaction and Transaction object if the transaction is a success.

{
    "data": {
        "id": "XYZPAY_5f68b5054073d",
        "status": "succeeded",
        "transaction_id": 3418,
        "card_id": null,
        "error": null,
        "created_at": "2020-09-21T14:13:25.000000Z",
        "updated_at": "2020-09-21T14:13:26.000000Z",
        "card": null,
        "transaction": {
            "data": {
                "id": 3418,
                "risk_score": 60,
                "last4": "1142",
                "cardholder_name": "John Doe",
                "expiry_date": "3/2030",
                "threeDSVersion": null,
                "postal_code": null,
                "shopper_reference": "USER_1",
                "shopper_phone_country": 90,
                "shopper_phone": "5466361359",
                "shopper_email": "[e-mail]",
                "shopper_name": "John Doe",
                "payment_method": "visa",
                "merchant_reference": "XYZPAY_5f68b5054073d",
                "status": "authorized",
                "external_id": "883600697605704D",
                "amount": 1000,
                "refunded_amount": null,
                "net_amount": 0,
                "currency": "EUR",
                "fail_reason": null,
                "metadata": {
                    "company": "sample",
                    "shopper_name": "John Doe"
                },
                "settled_at": null
            }
        }
    }
}

Auto-capturing & pre-authorisation

You can provide auto_capture=1 in the POST /transaction api request which will capture transaction as soon as it is authorised and it will also return a transaction with settled status.

Otherwise the payment will only be pre-authorized and you will need to capture the payment manually using POST /tranasction/{transactionId}/capture endpoint as described in Checkout documentation.

Authenticating the web payments

When a transaction requires an authentication you will have a PendingTransaction with a status request_auth

{
    "data": {
        "id": "XYZPAY_5f68b795154a4",
        "status": "request_auth",
        "transaction_id": null,
        "card_id": null,
        "error": null,
        "created_at": "2020-09-21T14:24:21.000000Z",
        "updated_at": "2020-09-21T14:24:22.000000Z",
        "card": null,
        "transaction": null
    }
}

The shopper should now be redirected to this URL which will handle the authentication.

https://javelin-url.com/pt/<PENDING_TRANSACTION_ID>/auth_web

# example for test environment
https://test.javelinhq.com/pt/XYZPAY_5f68b795154a4/auth_web

# example for live environment
https://test.javelinhq.com/pt/XYZPAY_5f68b795154a4/auth_web

This page will handle the authentication process and the shopper will be redirected back to return_url in the POST /transaction API request with pt_id query parameter. So the user will be redirected back to https://your_redirect.url?pt_id=XYZPAY_5f68b795154a4 in the example.

You can now use GET /pendingTransaction/{pendingTransactionId} in order find out the authentication result.

Need help? Contact Javelin support