Generate a Client Token
Get an API Key
You require an API Key to talk with our APIs. Head to the Developers area to manage your API keys. The Developers area refers to Primer Sandbox environment where you can try out and test Primer integration.
Never share your API Key, only your backend should have access to it.
Find out more about API Keys in our API Reference
Generate a Client Session
A client session is the starting point for integrating payments at Primer.
You can attach all the metadata associated with the order to the client session, and generate a clientToken, a temporary key used to initialize Universal Checkout.
The information you include in the client session is used in the Dashboard to conditionally route payments with Workflows, and activate payment methods and other features in Universal Checkout, so pass as much information as you can.
Here is a how the client session request to the Primer API should look like:
POST/client-session
12345678910111213
# Generate a client token with cURLcurl --location --request \ POST 'https://api.sandbox.primer.io/client-session' \ --header 'X-Api-Key: <YOUR_API_KEY>' \ --header 'X-Api-Version: 2021-10-19' \ --header 'Content-Type: application/json' --data '{ "orderId": "<YOUR_ORDER_ID>", "currencyCode": "GBP", "amount": 1200, "customerId": "<YOUR_CUSTOMER_ID>" "order": { "countryCode": "GB" } }'
Example Response
12345678910
{ "clientToken": "<THE_CLIENT_TOKEN>", "clientTokenExpirationDate": "2021-08-12T16:14:08.578695", "orderId": "<YOUR_ORDER_ID>", "currencyCode": "GBP", "amount": 1200, "customerId": "<YOUR_CUSTOMER_ID>", "metadata": {}, "warnings": []}
As a rule of thumb, pass as much information as you can when creating the client session. As a minimum, make sure to pass:
orderId
currencyCode
amount
order.countryCode
Set up the Universal Checkout
Step 1. Install the SDK
This SDK requires React Native v0.63 or higher.
Add the SDK package with yarn or npm:
12345
# With yarnyarn add @primer-io/react-native # With npmnpm i @primer-io/react-native --save
When the SDK packages finish installing, navigate to the /ios
folder and run pod install
.
Check out the troubleshooting section if you experience problems building the app.
For specific versions of the SDK, please refer to the changelog.
Step 2. Create a Client Session
Once the SDK is added, create a client session (generated on your backend with a Primer API key)
and store the returned clientToken
string parameter.
Provide any order/customer details when creating the client session. For more info on what information can be passed in, please refer to the example above and the Client Session API.
12
// Ask your backend to create a client sessionconst clientToken = await createClientSession()
Step 3. Configure Payment Callback
The SDK emits a payment method token that you should use to create a payment with Primer's Payment API.
To handle this, define the onTokenizeSuccess
callback like below:
12345678910111213141516171819
const onTokenizeSuccess = async (req, res) => { try { const payment = await createPayment({ paymentMethod: req.token, }) // resume SDK in case of required action, e.g. "3DS_AUTHENTICATION" if (payment.requiredAction) { setPaymentId(payment.id) // store the payment id. // resume the SDK with the payment's client token. res.handleNewClientToken(payment.requiredAction.clientToken) } else if (payment.status in ['FAILED', 'DECLINED', 'CANCELLED']) { res.handleError(errorMessage) } else { res.handleSuccess() // show success screen. } } catch (e) { res.resumeWithError(errorMessage) }}
Step 4. Configure Resume Callback
Next you should configure the onResumeSuccess
callback.
This is for scenarios where a create payment request results in a required action (see code snippet above)
and the payment is expected to be resumed later on.
12345678910111213141516171819
const onResumeSuccess = async (req, res) => { try { const payment = await resumeSession({ paymentId, resumeToken: req, }) if (payment.requiredAction) { setPaymentId(payment.id) // store the payment id. // resume the SDK with the payment's client token. res.handleNewClientToken(payment.requiredAction.clientToken) } else if (payment.status in ['FAILED', 'DECLINED', 'CANCELLED']) { res.handleError(errorMessage) } else { res.handleSuccess() } } catch (e) { res.handleError(errorMessage) }}
Step 5. Show Universal Checkout
Finally, pass in the clientToken
string and callbacks as arguments, and show the checkout.
12
// show Universal Checkout with above client token and config.Primer.showUniversalCheckout(clientToken, { onTokenizeSuccess, onResumeSuccess })
And voilà, you're all set!
Create a Payment
Once you've received a paymentMethodToken
from Universal Checkout, use it to create a payment.
Payment request POST/payments
1234567891011
curl --location --request \ POST 'https://api.sandbox.primer.io/payments' \ --header 'X-Api-Key: <YOUR_API_KEY>' \ --header 'X-Api-Version: 2021-09-27' \ --header 'X-Idempotency-Key: <YOUR_IDEMPOTENCY_KEY>' \ --data '{ "orderId": "<YOUR_ORDER_ID>", "amount": 800, "currencyCode": "GBP", "paymentMethodToken": "<PAYMENT_METHOD_TOKEN>", }'
- orderId
- your unique order ID
- amount
payment amount
example in currency (USD) with minor units:700
for \$7.00
example in currency (JPY) without minor units:100
for ¥100- currencyCode
ISO 4217 three-letter currency code:
USD
for US dollars- paymentMethodToken
paymentMethodToken
obtained from Universal Checkout or the Payment Methods API
Data passed in the payment request overwrites any data passed in the clientToken
.
See more request options in the API Reference.
Payment response
The payment request is synchronous. It will trigger a Workflow and return a payment object containing, among other things, the payment status. In circumstances where the payment flow is asynchronous, you may receive a status of PENDING
.
12345678910111213
// 2XX response { "id": "slklmjh4", "status": "AUTHORIZED", "orderId": "<YOUR_ORDER_ID>", "currencyCode": "GBP", "amount": 800, "paymentMethodToken": "<PAYMENT_METHOD_TOKEN>" // ... additional attributes for the Payment object // ... see API ref}
Did It Work?
If everything went well, you should be able to see the payment you just created on your dashboard under the Payments menu.
PAYMENT.STATUS
event.If you are not yet ready to receive webhooks, you can use https://webhook.site to test your implementation.