Tutorials

Set up iFrame

7min

How to set up your iFrame to integrate with P2C

As a Cross River merchant partner, suppose you prefer not to hold the Personally Identifiable Information (PII) of your customers. This could include, for example, customer debit card numbers and security details. iFrames offer a solution to PII problem. The Cross River iFrame gives you a simple interface to capture debit card details. You can easily add an iFrame to your website.

Your customer's card details pass through directly to Cross River. They are not stored on your servers.

In this tutorial, you'll learn how to:

✅ Register the relevant webhooks

✅ Set up an iFrame to integrate with P2C

This tutorial assumes you have a knowledge of APIs and how they work. Refer to the API overview page  for more details.

The tutorial uses these API endpoints:

API

Description

Add an iFrame into your site

The tutorial uses these webhooks:

Webhook

Description

CardAuthorized

  • Reports when a card authorization attempt is completed
  • Shows you the status of the card

Before you begin

Make sure you have:

Register the relevant webhook events

Use the POST /api/WebhookRegistrations endpoint to register to receive the webhooks available for P2C. These webhooks report relevant events back to your system in real-time. This keeps you up to date on all card activities.

The CardAuthorized webhook reports when a new card was authorized on our system.

No webhook received

Were you able to sign up for a card but didn’t get a webhook? The webhook function call might not be returning a 200 (“success”) message to Cross River.

Set up your iFrame

  1. Authenticate into the Cross River system. This returns a token to you.
  2. Use the token to call POST api/IframeConfiguration/BuildSignupCardUrl. The endpoint will return a response containing a unique URL. That URL is valid for 5 minutes.
  3. Pass the URL into the src attribute of the iFrame.

Attributes for building the iFrame

requestId

string

The GUID that enables the application to link request with response

customerReferenceNumber

string

A 4-digit code, assigned by the merchant, to identify the cardholder

domain

string

The name of a valid top-level internet domain where consumers will use the iFrame. For example, myfintech.com. This domain must appear in the Cross River allowlist.

successContinueNavigationPoint

string

The landing page you are directed to if the sign up was successful

failureContinueNavigationPoint

string

The landing page you are directed if the sign-up wasn't succeessful

firstName

string

Cardholder's first name

lastName

string

Cardholder's last name

address1

string

Primary location details of cardholder. For instance, street name, house or building number, and PO box. Maximum 255 characters.

address2

string

Secondary location details of cardholder. For instance, number of apartment or floor. Maximum 255 characters.

city

string

City full name

state

string

2-letter code of the cardholder's state

countryCode

string

2-letter Country code (2 letters)

zipCode

string

ZIP code

email

string

A valid cardholder email address, for example, [email protected]

phoneNumber

string

Phone number, no dashes required

showOptionalFields

boolean

True if optional fields will appear in the iFrame, otherwise false

Sample request


Response attributes

result

string

Result of whether or not the source URL was added to our server.

Success or fail.



isSuccessful

boolean

True if a unique URL was built successfully, otherwise false

Sample response




🤔
Have a question?
Our super-smart AI, knowledgeable support team and an awesome community will get you an answer in a flash.
To ask a question or participate in discussions, you'll need to authenticate first.