B2B Customer Care API Use Case

How do I lock or unlock a wallet account for a customer?

Paul has exceeded the number of failed password attempts and his wallet is now locked. He calls to have the account unlocked. Which API calls are used to complete this request?

  1. Look up the customer account.
  2. Verify the customer's identity in accordance with your company's guidelines.
  3. Unlock the account.

Look up the customer account

Design your customer care portal so that when the support representative inputs one of the supported search parameters it triggers a retrieveCustomerLookupInfo request to the B2B API that is populated with the input search parameters. The following request sample uses the phone number.

Remember to replace Issuing Partner token with the encrypted authorization token assigned to the Issuing Partner by Paydiant.

POST https://api-b2b.certification.paydiant.com.>/b2b-gateway/customers/lookup
Authorization: Basic Issuing Partner token

{  
  "retrieveCustomerLookUpInfoRequest":{  
    "messageHeader":{  
      "partnerId":"",
      "messageId":"",
      "versionId":"",
      "environmentId":""
    },
    "phone":"5089991234"
  }
}

Since phone is not unique per issuing partner, the response might return multiple matching profiles. Therefore, the results returned to the portal must also provide the additional information that the support representative needs in order to isolate the correct record.

{  
  "retrieveCustomerLookUpInfoResponse":{  
    "messageHeader":{  
      "partnerId":"",
      "messageId":"",
      "versionId":"",
      "environmentId":""
    },
    "status":{  
      "statusCode":"SUCCESS",
      "statusDescription":"Done",
      "errors":[  

      ]
    },
    "configurationDetails":[  

    ],
    "customerLookUpInfo":[  
      {  
        "devices":[  

        ],
        "additionalCustomerInformation":[  
          {  
            "key":"birthday",
            "value":"08281970"
          }
        ],
        "customerUri":"certnew:entity:customer#bb3c20c6-456a-4484-891d-daaa2ee22da4",
        "issuingPartnerUri":"certnew:entity:issuingpartner#d72bb2cd-34f9-441e-9daf-4f3ef2838bcb",
        "partnerUri":"paydiant:entity:partner#5df9ba6e-c3a5-4c7e-9f22-6812a069683a",
        "createDate":1493069461632,
        "issuingPartnerShortName":"certnew",
        "active":true,
        "locked":false,
        "email":"olivia_wallet_user@hotmail.com",
        "emailPending":null,
        "customerId":"latYxDdNJhzm",
        "username":"olivia_wallet_user@hotmail.com",
        "firstName":"Olivia",
        "lastName":"Smith",
        "address1":"2750 Grove St",
        "address2":"Apt 2",
        "city":"Newton",
        "country":"USA",
        "state":"MA",
        "zip":"02246",
        "phone":"9991234444",
        "passwordChangedDate":1493069461703,
        "passcodeChangedDate":1493069461705,
        "securityQuestionsChangedDate":1493069461705,
        "lastLoginDate":null,
        "emailVerified":true,
        "emailVerifiedDate":null
      }
    ],
    "customerLookUpInfo":[  
      {  
        "devices":[  

        ],
        "additionalCustomerInformation":[  
          {  
            "key":"birthday",
            "value":"07101969"
          }
        ],
        "customerUri":"certnew:entity:customer#bb3c20c6-456a-4484-891d-daaa2ee22da4",
        "issuingPartnerUri":"certnew:entity:issuingpartner#d72bb2cd-34f9-441e-9daf-4f3ef2838bcb",
        "partnerUri":"paydiant:entity:partner#5df9ba6e-c3a5-4c7e-9f22-6812a069683a",
        "createDate":1454792210632,
        "issuingPartnerShortName":"certnew",
        "active":true,
        "locked":true,
        "email":"pauls_wallet@yahoo.com",
        "emailPending":null,
        "customerId":"vmiTxZcaSEym",
        "username":"pauls_wallet@yahoo.com",
        "firstName":"Paul",
        "lastName":"Casey",
        "address1":"445 Graceland Drive",
        "address2":"",
        "city":"Laguna Beach",
        "country":"USA",
        "state":"CA",
        "zip":"92651",
        "phone":"9991234444",
        "passwordChangedDate":1454792210632,
        "passcodeChangedDate":1454792210632,
        "securityQuestionsChangedDate":1454792210632,
        "lastLoginDate":null,
        "emailVerified":true,
        "emailVerifiedDate":null
      }
    ]
  }
}

The preceding response sample shows two records returned for the same phone number. Note that the second record is for a user named Paul whose locked status is true.

Once the support representative has isolated and verified the identity of the caller, in accordance with their company standard, the portal needs to provide a way for the support representative to select the correct record. The user data from that record is then used to populate subsequent calls.

Need more? See retrieveCustomerLookUpInfo in the B2B Customer Care Reference Guide.

Verify the customer's identity

Follow your company's guidelines to verify that you are working with the correct customer.

Unlock the account

The Paydiant Platform supports several scenarios that result in a wallet account becoming restricted in some way.

Since a customer's registered wallet account has two status properties: active and locked, different combinations of these states can result in the wallet account becoming unusable.

For example:

  • A wallet can become locked (but still active) when a user has exceeded the number of failed login attempts allowed by the Issuer.

  • Furthermore, a wallet can be linked with multiple devices. So, a husband and wife might both have access to the same registered wallet account on their separate phones. Each device has an active status property and can be deactivated without affecting the entire wallet account and without deleting the device from the wallet association, allowing the device to be reactivated at a later time. In this use case, the user's wallet is active, but has become locked due to consecutive invalid login attempts.

When an account is locked, a wallet can only only be activated or deactivated explicitly through a B2B API request.

The B2B API does not have an endpoint to edit the locked attribute directly. However, when a customer's active property is toggled from false to true, it automatically also resets the locked property.

To unlock a locked customer wallet, invoke the updateCustomerActivation call, populating the customer identification properties with those returned in the customer lookup response, and setting activate to false. Then, invoke the same call again, setting the activate property to true, which will automatically reset the locked value to false.

Remember to replace IssuingPartnertoken with the encrypted authorization token assigned to the Issuing Partner by Paydiant.

//POST https://api-b2b.certification.paydiant.com/b2b-gateway/customers/activation
//Authorization: Basic IssuingPartnertoken

{  
  "updateCustomerActivationRequest":{  
    "messageHeader":{  
      "partnerId":"",
      "messageId":"",
      "versionId":"",
      "environmentId":""
    },
    "customerUri":"certnew:entity:customer#e1f42d4d-587a-46c1-8de9-2b21846c02c0",
    "issuingPartnerUri":"certnew:entity:issuingpartner#d72bb2cd-34f9-441e-9daf-4f3ef2838bcb",
    "partnerUri":"paydiant:entity:partner#5df9ba6e-c3a5-4c7e-9f22-6812a069683a",
    "activate":"false"
  }
}

The successful response returns no payload, but confirms a status of SUCCESS. Invoke the call again to reactivate the wallet user.

//POST https://api-b2b.certification.paydiant.com/b2b-gateway/customers/activation
//Authorization: Basic (*Provide the encrypted authorization token assigned to the issuing partner by Paydiant here*)

{  
  "updateCustomerActivationRequest":{  
    "messageHeader":{  
      "partnerId":"",
      "messageId":"",
      "versionId":"",
      "environmentId":""
    },
    "customerUri":"certnew:entity:customer#e1f42d4d-587a-46c1-8de9-2b21846c02c0",
    "issuingPartnerUri":"certnew:entity:issuingpartner#d72bb2cd-34f9-441e-9daf-4f3ef2838bcb",
    "partnerUri":"paydiant:entity:partner#5df9ba6e-c3a5-4c7e-9f22-6812a069683a",
    "activate":"true"
  }
}

You may wish to design the support interface to simplify the customer status display.

Unlock Confirmed

Need more? See updateCustomerInformation in the B2B Customer Care API Reference Guide.

What's next?

Feedback

Have feedback?

Let us know.