Create Checkout
The OpenAPI specification for this checkout operation can be found here.
Step 1 (You send the consumer to us)
On successful checkout you will receive back a paymentUrl in the response, the consumer must be redirected to this url to action the payment on the gateway.
NO iFRAMES
iFrames are not allowed for security reasons, a full page redirect to the paymentUrl is required.
Step 2 (The consumer actions the payment with us and we send them back to you)
If the consumer successfully makes the payment they will be redirected back to the confirmRedirectUrl you supplied in the checkout request.
If the consumer decides to cancel making payment they will be redirected back to the cancelRedirectUrl you supplied in the checkout request.
Step 3 (We notify you securely of successful payment)
In the case of a successful payment a callback will be posted back to your server to the checkoutStatusCallbackUrl you supplied during the gateway installation.
This callback request will be signed with your secret signing key and you must validate it, we expect a HTTP 200 status back from your server to confirm receipt.
It's important to always validate the "checkoutPaymentStatus" in the callback payload, to ensure it's either PAID or PAID_PENDING_CALLBACK before accepting payment confirmation.
We will attempt to send the callback to your server 3 times, afterwhich we will move the callback to a dead letter queue.
tip
If you specify a checkoutCallbackFailuresEmail during the gateway installation you will receive an email notifying you every time a callback fails. The email will also contain the checkout detail at the time of the failure.
tip
If you would also like to receive a callback when a consumer cancel's a checkout, then please contact your account manager to enable this. The "checkoutPaymentStatus" in the callback payload would then be CANCELLED_BY_CONSUMER.
Here is an example of a successful PayJustNow checkout create request and response:
POST /v2/create HTTP/1.1X-Signature: Nlz3rton0ToLX+rHVy8gydx3faa5EL/mIgIQBXEWTpU=X-Merchant-Account-ID: 1Content-Type: application/jsonUser-Agent: PostmanRuntime/7.31.1Accept: */*Postman-Token: a6e664a4-951d-4c62-a9e8-6810aa955e86Host: sandbox-checkout.payjustnow.ioAccept-Encoding: gzip, deflate, brConnection: keep-aliveContent-Length: 1442 { "requestId": "idempkey", "payjustnow": { "merchantOrderReference": "yourorderref", "orderAmountCents": 200000, "orderItems": [ { "name": "UGG Boots Purple Size 6", "sku": "UGG-BB-PUR-06", "quantity": 2, "priceCents": 100000, "imageUrl": "https://merchantstore.com/uggboots/purp6.jpeg", "pageUrl": "https://merchantstore.com/uggboots", "searchTerms": [ "ugg", "boots", "purple" ], "category": "Fashion Apparel" } ], "orderExpiryMinutes": 60, "customer": { "firstName": "Matthew", "lastName": "Monson", "email": "matthew@payjustnow.com", "phoneNumber": "0786542314" }, "billingAddress": { "addressLine1": "123 Billing Street Line 1", "addressLine2": "Billing Street Line 2", "city": "Cape Town", "province": "Western Cape", "postalCode": "8001" }, "shippingAddress": { "addressLine1": "123 Shipping Street Line 1", "addressLine2": "Shipping Street Line 2", "city": "Cape Town", "province": "Western Cape", "postalCode": "8001" }, "confirmRedirectUrl": "https://merchantstore.com/order/xyz/success", "cancelRedirectUrl": "https://merchantstore.com/order/xyz/cancel" }, "checkoutTotalCents": 200000, "clickTraceId": "S09PRE9PRkVCMjAyM0tPT0RPT0ZFQjIwMjN1bmRlZmluZWQ="} HTTP/1.1 200 OKDate: Mon, 20 Mar 2023 10:49:22 GMTContent-Type: application/jsonContent-Length: 1410Connection: keep-alivex-amzn-RequestId: c8e32020-bc90-4ced-88d4-5ea33c99d352x-amz-apigw-id: CE4HeGa8joEFjnQ=X-Amzn-Trace-Id: Root=1-64183a2f-7fc0f1e504831dc709dd787c { "requestId": "idempkey", "checkoutToken": "v2.1.34763d6d-7dc7-4a8c-aa51-bcc49d1cfa60", "checkoutTotalCents": 200000, "paymentUrl": "https://sandbox.payjustnow.com/api/v2/app/checkout/v2.1.34763d6d-7dc7-4a8c-aa51-bcc49d1cfa60", "checkoutPaymentStatus": "PENDING_ORDER", "merchantOrderReference": "yourorderref", "clickTraceId": "S09PRE9PRkVCMjAyM0tPT0RPT0ZFQjIwMjN1bmRlZmluZWQ=", "createdAt": "2023-03-20T10:49:20.354Z", "updatedAt": "2023-03-20T10:49:20.354Z", "expiresAt": "2023-03-20T11:49:20.354Z", "payjustnow": { "merchantOrderReference": "yourorderref", "orderAmountCents": 200000, "shippingAddress": { "addressLine1": "123 Shipping Street Line 1", "addressLine2": "Shipping Street Line 2", "province": "Western Cape", "city": "Cape Town", "postalCode": "8001" }, "confirmRedirectUrl": "https://merchantstore.com/order/xyz/success", "cancelRedirectUrl": "https://merchantstore.com/order/xyz/cancel", "billingAddress": { "addressLine1": "123 Billing Street Line 1", "addressLine2": "Billing Street Line 2", "province": "Western Cape", "city": "Cape Town", "postalCode": "8001" }, "orderItems": [ { "quantity": 2, "searchTerms": [ "ugg", "boots", "purple" ], "imageUrl": "https://merchantstore.com/uggboots/purp6.jpeg", "name": "UGG Boots Purple Size 6", "priceCents": 100000, "pageUrl": "https://merchantstore.com/uggboots", "sku": "UGG-BB-PUR-06", "category": "Fashion Apparel" } ], "orderExpiryMinutes": 60, "customer": { "firstName": "Matthew", "lastName": "Monson", "phoneNumber": "0786542314", "email": "matthew@payjustnow.com" } }, "merchantAccountId": "1"}WAF
The gateway is protected by a WAF. If you receive a HTTP 403 response back when trying to create a checkout, it most likely means there is a something in your request that the WAF does not like. Please avoid using localhost and ip addresses in the redirect url fields.
tip
orderExpiryMinutes can be adjusted to between a minimum of 10 and maximum of 7200 minutes, afterwhich no further updates will be permitted on the checkout.
tip
The requestId value in the request payload is for idempotence, this guarantees you will always get the same checkout create response back for the same requestId.
Idempotent responses will contain idempotent-replay: true in the response headers.