Tutorial: Setting up your iframe to integrate with P2C

If as a merchant, you don't want to collect or hold your customer’s Personally Identifiable Information (PII) such as their debit card number and security information, you can use the Cross River iframe. Our iframe is a simple interface that you can easily add to your website to capture debit card details.

Your customer's card details will pass through directly to Cross River and not be stored on your servers.

Before you begin

Make sure you have:

API credentials received from the Integration Team
Successfully registered to receive webhook event notifications
Contacted the Integration Team to register the domains in which you'll be embedding the iframe

Register to receive a webhook events

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

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

Note: No webhook received
If you were able to sign up a card but don't receive a webhook, it's possible that the webhook endpoint isn't returning a 200 to our system.

Setting up your iframe

Authenticate into our system and a token is returned to you.
Use that token to call POST api/IframeConfiguration/BuildSignupCardUrl.
The endpoint will return a response containing a unique URL which is valid for 5 minutes.
Pass the URL into the src attribute of the iframe.

Attribute table for setting up your iframe

Attribute	Description
requestId string	Transaction request ID. Required
customerReferenceNumber string	Customer's reference number. Required
domain string	The domain in which the iframe will be used. Required
successContinueNavigationPoint string	The landing page the customer is directed to if the sign up was successful. Optional
failureContinueNavigationPoint string	The landing page the customer is directed to if the sign up was unsuccessful and failed. Optional
firstName string	Cardholder first name. Optional
lastName string	Cardholder last name. Optional
address1 string	Cardholder address, line 1. Optional
address2 string	Cardholder address, line 2. Optional
city string	Cardholder city. Optional
state string	Cardholder State. Optional
countryCode string	2 letter country code. Optional
zipCode string	Zip code. Optional
email string	Email address. Optional
phoneNumber string	Cardholder phone number. Optional

Sample request in JSON

{
  "requestId": "24jla71k-fjl1-08m8-bks7-naxk8773bxr4",
  "customerReferenceNumber": <reference number>,
  "domain": www....com,
  "successContinueNavigationPoint": "www.....com",
  "failureContinueNavigationPoint": "www.....com",
  "firstName": Jana,
  "lastName": Parker,
  "address1": 257 Dalton Groves,
  "address2": null,
  "city": Barton City",
  "state": MI,
  "countryCode": US,
  "zipCode": 48705,
  "email": <[email protected]>,
  "phoneNumber": "null",
}

Sample response from POST api/IframeConfiguration/BuildSignupCardUrl

The URL that's returned contains unique information specific for you.

A true response to isSuccessful means that a unique URL was built successfully.

{
"version":"1.0.0.0",
"result":"https://pushtopayiframestg.crbcos.com/post-cards/?t...",
"isSuccessful":true
}

If the iframe was integrated correctly, the iframe contents show.

Troubleshooting

If the iframe doesn't load, a failure landing page shows.
If more than 5 minutes passes, the OTC will be stale and the iframe content disappears - Session expired! shows.
If you click submit right when the OTC expires you may receive an authentication error.