Overview

For apps without PCI (Payment Card Industry) certification: You must integrate the card binding SDK provided by OSL Pay. This is the industry-compliant solution.

For apps with PCI certification: You may choose either of the following integration modes based on your business needs.

Integrate the Card Binding SDK

Data flow: Users’ sensitive card information is collected, processed, and stored directly by OSL Pay’s SDK. Your system will not access or store any sensitive data.
UI experience: The payment flow UI is provided by the SDK. Basic branding (e.g., colors, logo) is usually allowed, but overall interaction design and flexibility are limited.

Integrate via OpenAPI

Data flow: Users’ card information passes through your server environment.
Compliance responsibility: Your system must fully comply with PCI DSS security standards at all times and assume full security and compliance responsibility.
UI experience: You have full control to design the card binding interface, enabling seamless integration with your app and highly flexible interactions.

Interaction flow diagram

Integration example

Currently, native SDK is not supported. Apps must integrate using the web-based approach.

<!-- sandbox -->
<script src="https://ramptest.osl-pay.com/js/op-frames.min.js"></script>
<script>
  // nitialization
  OSLPayFrames.init({
    boundCardToken: "******",
  });
  // Calling card binding
  OSLPayFrames.dispatch("submitCard");
</script>
<div id="oslpayFrame"></div>

<!-- production -->
<script src="https://ramp.osl-pay.com/js/frames.min.js"></script>
<script>
    // nitialization
    OSL-PayFrames.init({
        boundCardToken: '******'
    })
    // Calling card binding
    OSL-PayFrames.dispatch('submitCard')
</script>

<div id="OSL-PayFrame"></div>

SDK methods

Method	Description	Example
`init(object: InitParmas)`	Initializes and loads the form. See `InitParams` for details.	OSLPayFrames.init(object)
`addEventHandler(event: DispatchEventName, handler)`	Adds a handler for a specified `event`. event must be a valid event name (see `DispatchEventName`). `handler` is the callback function.	OSLPayFrames.addEventHandler(Events.CARD_TOKENIZED, (event) => )
`removeEventHandler(event: DispatchEventName, handler)`	Removes a specific handler previously added via `addEventHandler`. `event` must be a valid event name (see `DispatchEventName`). `handler` is the function to remove.	`OSLPayFrames.removeEventHandler(Events.CARD_TOKENIZED, (event) => {})`
`removeAllEventHandlers(event: DispatchEventName)`	Removes all listeners attached to the specified event. `event` must be a valid event name (see `DispatchEventName`).	`OSLPayFrames.removeAllEventHandlers(Events.CARD_TOKENIZED)`
`dispatch(event: DispatchEventName, handler)`	Manually triggers a specified event. `event` must be a valid event name (see `DispatchEventName`). `handler` is an optional callback function.	`OSLPayFrames.dispatch(Events.CARD_SUBMIT, (e) => {})`

`InitParmas`

Parameter	Description	Required	Default
`boundCardToken`	Card binding token	Yes	`undefined`
`locale`	Language	No	See supported languages
`getContainer`	DOM element to insert the iFrame	No	`document.querySelector("#OSLPayFrame")`
`fields: FieldsParams`	Form options. See `FieldsParams` for details	No	`{ phone: false, billState: false }`
`style: StyleParams`	If you want to override default styles and customize CSS, pass a style object to the `init` method. See `StyleParams` for details	No

`DispatchEventName`

Event name	Javascript constant	Description	Return value
`submitCard`	`CARD_SUBMIT`	Triggered when the card form is submitted	`{ tokenValid: true/false, status: true/false, cardId: "622***111" }`
`resetForm`	`CARD_RESET_FORM`	Triggered when the card form is reset	`undefined`
`isCardValid`	`CARD_IS_VALID`	Returns whether the card validation succeeded	`{ isValid: true / false }`

`FieldsParams`

Event name	Javascript constant	Description
`phone`	`FIELD_PHONE`	Cardholder’s phone number including country code
`billState`	`FIELD_BILL_STATE`	Cardholder’s state/province. Required if the card is issued in the US or Canada; optional for cards issued in other countries/regions.

`StyleParams`

Property	Description
backgroundColor	iFrame background color
input	Styles for input fields. Accepts an object with the following properties: `color`, `backgroundColor`, `fontSize`, `height`, `padding`, `rounded`, `border`
label	Styles for labels. Accepts an object with the following properties: `color`, `paddingBottom`, `fontSize`
focus	Styles are applied when an element gains focus. Accepts an object with the property: `color`
invalid	Styles applied when validation fails. Accepts an object with the following properties: `color`, `padding`, `fontSize`
placeholder	Styles for input placeholders. Accepts an object with the property: `color`
select	Styles for the default select box. Accepts an object with the properties: `options`, `backgroundColor`, `border`. `options` accepts an object with the following properties: `activeBackgroundColor`, `fontSize`, `color`, `height`

For example, a Frames instance initialized with the following parameters:

OSLPayFrames.init({
  boundCardToken: "YOUR-CARD-TOKEN",
  style: {
    backgroundColor: "#000000",
    padding: "10px 5px",
    input: {
      color: "#e7d2c4",
      backgroundColor: "#F8F6F9",
      fontSize: "20px",
      height: "80px",
      padding: "10px 10px 10px 10px",
      rounded: "20px",
      border: "1px solid #e7d2c4",
    },
    label: {
      color: "#e7d2c4",
      fontSize: "14px",
      paddingBottom: "15px",
    },
    focus: {
      color: "#afd523",
    },
    invalid: {
      color: "#9a1313",
      fontSize: "20px",
      padding: "10px 10px 10px 10px",
    },
    placeholder: {
      color: "#ba8397",
    },
    select: {
      backgroundColor: "#e7d2c4",
      border: "1px solid #9a1313",
      options: {
        activeBackgroundColor: "#bcc397",
        fontSize: "20px",
        color: "#26bfd4",
        height: "64px",
      },
    },
  },
});

SDK events

Event name	Javascript constant	Description
`cardTokenizationValid`	`CARD_TOKENIZATION_VALID`	Triggered after card binding token validation is completed. Return value: `isValid: true / false`
`cardValidationChanged`	`CARD_VALIDATION_CHANGED`	Triggered when the card validation status changes. Return value: `isValid: true / false`