Guides

Hosted UX API

Hosted UX API for PCI Widget

This API is responsible for configuring or retrieving details of PCI (Payment Card Industry) for a customer account (entirely on Green Dots end). This allows a partner to stay out of scope from PCI Compliance while still providing the customer the ability to perform activities involving card data. This API takes an "activity" as well as a "success" and an "error" URL as request and provides a GD hosted URL in response. The customer can be directed to this GD-hosted URL as a web-view in the partner's app for a seamless experience for the customer.

The Hosted UX API found directly below is the most recent and up to date version of our PCI Widget API functionality and should be the only PCI Widget API used.

However, please note that we have also provided details for our DEPRECATED pciConfig API that is an older version of the PCI Widget API for any partners still using it while they prepare to transition to the new and enhanced Hosted UX version.

Hosted UX API

This API is used to start the Hosted UX work flow (PCI Widget). At the beginning of the flow the user must be redirected to the url in the response. This will kick off the hosted experience for the user. At the end of the work flow, the user will be redirected to one of the specified URLs (successUrl,errorUrl).

  • If successful, a LINK_CARD activity will have a “linkid” value returned in the query string.
  • If an error occurs, then the “code” and “subcode” values will be returned in the query string. The token is only valid for 5 minutes.

Screenshot References

API Call Structure

POST /programs/{programCode}/hosted/ux

Route Parameters

Parameter nameTypeValueDescription
programCodestringvariesThis property identifies the program type of the account to be created.

Headers

Header nameTypeValueDescription
X-GD-RequestIduuidvariesThis property is used to uniquely identify each request.

Request

{ 
  "activity": "string", 
  "activityData": { 
     "AccountIdentifier": "string", 
     "CustomerToken": "string", 
     "CustomerType": "string", 
     "LinkId": "string", 
  }, 
  "successUrl": "string", 
  "errorUrl": "string" 
}

Request Parameters

Property nameValueDescription
activityenumIndicates what activity to initiate.

Allowed activity values:

1. CARD_ACTIVATION
2. CARD_SETPIN
3. CARD_DETAILS
4. LINK_CARD
5. UPDATE_LINK
activitydata.AccountIdentifierGUIDPopulate “AccountIdentifier” when CustomerType=“baas”.
activitydata.CustomerTokenstringPopulate “CustomerToken” when CustomerType=“external”.
activitydata.CustomerTypeenumIndicates the type of customer. Valid values are “baas” or “external”.
activitydata.LinkIdcard link idOnly used for UPDATE_LINK activity.
successUrlurlUrl to redirect the customer after successful activity completion.
errorUrlurlUrl to redirect to on Error.

📘

Please note you will either provide the Account ID, OR provide both the Customer Token and Customer Type

Response

{ 
  "url": "string", 
  "responseDetails": [ 
    { 
      "code": 0, 
      "subCode": 0, 
      "description": "string", 
      "url": "string" 
    } 
  ] 
}

Link Card Activity Sample Request + Response

POST /programs/{programCode}/hosted/ux

Sample Request

{
  "activity": "LINK_CARD",
  "activityData": {
    "AccountIdentifier": "dd11f054-67ee-4e84-99bb-4f60f31489ab",
  },
  "successUrl": "https://partner.com/success-return-url",
  "errorUrl": "https://partner.com/error-return-url"
}

Sample Response

{
  "url": "https://qa-partnername.go2bankonline.com/cardmanagement/link-card?code=eyJhbGciOiJSUzI1NiIjAzRjNFMTU0MzYyMDM1RUFBNzQxQUU1N0FGNTIyMDQwRTkiLCJ0eXAiOiJKV1QiDgzODkyYi0xZmJiLTRlNmMtYTk3OC01NDYzNDNmjoiUENJOlJlZGlyZWN0In0.oUOCIqa731pNBMRfJvKh-IEF5iC99oDMI7giTF5UbJDx32bzJC3ZgIGvpAZ_HzwIeha1kaGvpwj86577szX-wBo2ndgoMhxM0PfSVyZj2sNK7STRgdIrTFeY8v5S-4XLuOdoGx_EcOH5jxVJG3rikiuAiGI_dboKgZFZxOtB23C0ykt9u4EIrI-_sC5sLnTfeebgvtQC1InkJlP3W0w__yWClLhV7ZGL1tI2V2omUATGxVVhnrz4LkmOTpZNzhBIhjM0W6R3O89Hskn85nfxwu1bGy057oFRjbJ0Nvze5IyV8iNgSvCwjU5d0lH0LFmDeGbVfeRDmaLX1WsqqzIv-g&accountIdentifier=NA&programCode=NA&requestId=4892b-1fbb-4e6c-a978-5460ef3&sign=NA",
  "responseDetails": [
    {
      "code": 0,
      "subCode": 0,
      "description": "string",
      "url": "string"
    }
  ]
}

Card Details Activity Sample Request + Response

POST /programs/{programCode}/hosted/ux

Sample Request

{
  "activity": "CARD_DETAILS",
  "activityData": {
    "AccountIdentifier": "dd11f054-67ee-4e84-99bb-4f60f31489ab"
  },
  "successUrl": "https://partner.com/success-return-url",
  "errorUrl": "https://partner.com/error-return-url"
}

Sample Response

{
  "url": "https://qa-partnername.go2bankonline.com/cardmanagement/card-info?code=d38e8c11-8ad2-b9dd8b480d8a&accountIdentifier=04500777-ED69-1FAE7E971F8C&programCode=examplecode&requestId=e06-84bf-45de-abaa-be5a6706eab7&sign=EBD48DA237A5884A730D3B937ABC47E4340330E1BF5106B9CC9",
  "responseDetails": [
    {
      "code": 0,
      "subCode": 0,
      "description": "string",
      "url": "string"
    }
  ]
}

Update Link Activity Request + Response

POST /programs/{programCode}/hosted/ux

Sample Request

{
  "activity": "UPDATE_LINK",
  "activityData": {
    "LinkId": "7bb66967-33d6-44d4-9040-c3dabcd233a6",
  },
  "successUrl": "https://partner.com/success-return-url",
  "errorUrl": "https://partner.com/error-return-url"
}

Sample Response

{
  "url": "https://pie-partnername.go2bankonline.com/cardmanagement/update-link?code=744f0301-a943-0173c24467d8&accountIdentifier=8F44-5882-4388-A496-97A9F9C239E6&programCode=examplecode&requestId=eac89eba-9a4b-49a2-b34a-8ef740aed67a&sign=280297985374B8AD3E8C866A63745315A3FC40EBC4B4B0D439630C",
  "responseDetails": [
    {
      "code": 0,
      "subCode": 0,
      "description": "string",
      "url": "string"
    }
  ]
}

Updated about 1 month ago