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:

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

  1. Authenticate into our system and a token is returned to you.
  2. 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.
  3. Pass the URL into the src attribute of the iframe.

Attribute table for setting up your iframe

AttributeDescription
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.

300

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.