Integration
| Requirement | Description |
|---|---|---|
1 | Load customer data into COS | Cross River (CR) must perform OFAC/PEP screens in our system (COS) at the time of onboarding and regularly after that. |
2 | Add unique cardholder identifier into COS | Cross River receives files from processors and from the networks with tokenized card numbers. The processor uses the tokenized card numbers as unique identifiers for each cardholder. To match cards with accounts, we need this unique identifier to be added to the cardholder’s COS customer record. CR expects that whenever a new card token is generated, you update this COS customer record. It makes no difference if the card is new or reissued. |
3 | For Commercial Card Partners: Link the businesses and cardholders in COS | Cross River requires Commercial card partners to create both business and cardholder customer records in COS. Use the beneficial owner API call to update the COS customer record. |
To add customer data in COS:
- After a successful KYC (know your customer) check, call the POST /core/v1/cm/customers endpoint in COS to create the cardholder’s customer account.
- OFAC uses the customer name, date of birth (DOB), and address. The Customer Identification Program (CIP) requires the customer social security number or government-issued ID (for non-US persons).
- The webhook event Core.Customer.Ofac.Changed is triggered and returns an initial status of Clear or Failed.
- If the status is Clear, you can approve and create the customer credit card facility on your side.
- If the status is Failed, the CR AML team investigates the case. The webhook event is triggered again, sending a status of Reviewing or Pending, indicating that a person is reviewing the case. This can take up to 48 hours. Very rarely, the CR team might reach out to you to ask for additional supporting documents. You will need to provide an email address for this. The Core.Customer.Ofac.Changed webhook returns any change in status, not just Reviewing or Pending.
- After reviewing, the CR team moves the status to either Clear or Positive. The webhook event fires again.
- If Clear, you can continue with approving and creating a credit card facility for your customer.
- If Positive, you must decline the application. This is quite rare.
- To trigger an OFAC/PEP failure in the Sandbox use these values in your call:
- For PEP, in the name object use the name Vladimir Putin to get a hit.
- For OFAC, in the name object use the name Francisco Javier Arellano Félix; and in the profile object use the birthdate 1969-12-11 (December 11, 1969)
- For OFAC entity, in the name object use the entityName value Blue Star Diamond
- Once the customer record is cleared, there is no longer a reason to subscribe to the specific customer webhook.
- Cross River scans customer records nightly for OFAC/PEP. If a customer hits OFAC during a nightly scan, our AML team will reach out via Zendesk to help clear.
- You must keep the customer records you create up to date.
- If a customer changes their name, address, email, or other details, use the Customer Management APIs to update their record.
- You can make this part of a nightly process.
- The scans take less than a second. Anything that needs manual review is taken care of within 3 business days.
- Status Definition Changes (applies to OFAC, PEP, and Internal List). Webhook event responses from this point on mean:
- Positive: Must be rejected (no change)
- Clear: Everything is fine (no change)
- Pending: The case is being reviewed (no change)
- Reviewing: A potential match within a category is being reviewed by CR and is pending a disposition. Previously this was Failed.
- Failed: There isn’t enough information to know the status (for example, RFI not responded to).
Cross River receives files from processors and from the networks that contain tokenized card numbers identifying each cardholder. We need to add these unique user identifiers to the COS customer record of each cardholder. This allows Cross River to track all the information that the card networks need to know about that customer's card and how they use it.
Add the identifier to the Customer ID section with this endpoint:
POST /core/v1/cm/customers/{id}/identifications
Use these values in the body of the request:
As always, if you have any questions, email [email protected].
When you provide cards to a business (and not directly to individual cardholders), both the business itself and each cardholder from that business have customer records in COS.
To ensure that the cardholder customer records are associated with the correct business customer record, you add each cardholder as a beneficial owner to the business record.
Associate the customer record with the business customer record using this endpoint:
POST /core/v1/cm/customers/{customerId}/beneficial-owners
In the body of the request, use the customer ID of the business issuing the company card for the customerId value, and the customer ID of the cardholder for the ownerCustomerId value. Enter Auth User for the ownerTitle value.
As always, if you have any questions, email [email protected].
Provide Cross River with the reports and data files described in this section.
To manage the daily and monthly obligations to the card networks, Cross River requires new Credit BIN Sponsor Partners or Platforms to provide the following Operational Supports via SFTP:
- Daily Net Settlement
- Monthly Spend and Interchange
- Monthly Chargeback
- Quarterly Reports
- Transaction data files
Cross River requires Partners or Platforms to send transaction details daily. These transaction files must minimally include the following elements:
- Transaction Reference ID
- Posted Date
- Transaction Amount
- Transaction Currency
- Return Amount
- Transaction Credit/Debit Indicator
- Transaction Status
- User Token Value
- Card Token Value
- Last 4 digits of PAN
- Merchant ID
- Merchant Name
- Merchant City
- Merchant Country
- Merchant State
- Merchant Category Code (MCC)
