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
﻿POST api/IframeConfiguration/BuildSignupCardUrl﻿ 
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:
﻿API credentials﻿
Successfully registered﻿  to receive webhook event notifications
Contacted the Integration Team to register the domains where you'll be embedding the iFrame
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
Authenticate into the Cross River system. This returns a token to you.
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.
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
{
  "requestId": "89clha9s-27ci-90ck-7jcs-8lksic02cjag",
  "customerReferenceNumber": "string",
  "domain": "string",
  "successContinueNavigationPoint": "string",
  "failureContinueNavigationPoint": "string",
  "firstName": "Joseph",
  "lastName": "Roll",
  "address1": "123 Main Street",
  "address2": "string",
  "city": "Venice",
  "state": "CA",
  "countryCode": "string",
  "zipCode": "66666",
  "email": "{email}",
  "phoneNumber": "string",
  "showOptionalFields": true
}
{
  "requestId": "89clha9s-27ci-90ck-7jcs-8lksic02cjag",
  "customerReferenceNumber": "string",
  "domain": "string",
  "successContinueNavigationPoint": "string",
  "failureContinueNavigationPoint": "string",
  "firstName": "Joseph",
  "lastName": "Roll",
  "address1": "123 Main Street",
  "address2": "string",
  "city": "Venice",
  "state": "CA",
  "countryCode": "string",
  "zipCode": "66666",
  "email": "{email}",
  "phoneNumber": "string",
  "showOptionalFields": true
}
﻿
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
{
  "version": "1.0.0.0",
  "result": "Success",
  "isSuccessfull": true
}
{
  "version": "1.0.0.0",
  "result": "Success",
  "isSuccessfull": true
}
﻿
﻿

API	Description
POST api/IframeConfiguration/BuildSignupCardUrl	Add an iFrame into your site

Webhook	Description
CardAuthorized	Reports when a card authorization attempt is completed Shows you the status of the card

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

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

🤔

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.

﻿

Updated 15 Oct 2024

Did this page help you?

Originate a push transaction

Originate a pull transaction