Reissue PIN

Owned by Ope Adeoye
Last updated: Apr 10, 2020
4 min read

With this service, the calling apps can reissue or reset the PIN linked to a card, wallet or bank account (if supported) on behalf of a customer. Apps will have to collect the current PIN (via auth details or when the provider challenges for it). This service is different from PIN change in that the new PIN will be set by the Provider. This service may use OTP to confirm the request from the customer.

Before you proceed: Please read this.

Commercial model

At agreed settlement cycles, the host will debit the configured beneficiary account of the app for the use of this API and share that fee with all participants. Fees will be determined by the provider.

Special configuration notes

  • OTP override: All providers of this service should implement OTP, but support the configuration of otp_override such that based on this configuration, they could be instructed to bypass the OTP requirement for an app.

  • SMS handler: All providers that need to do OTP validation can use the Send SMS and Send Email services on OnePipe to send their OTP.

Settlement & fees model

Model

How it works

Model

How it works

Invoice

The host client will invoice the calling app periodically for all calls to the endpoint.

Process flows

Sequence of calls

  1. App calls /transact with the right auth details (if supplied)

  2. Provider responds with WaitingForOTP or PendingValidation (if required)

  3. App calls /transact/validate to supply OTP if needed

  4. Provider responds with any of the completion codes Successful or Failed.

  5. To query the status of a transaction, the app can call /transact/query

 

INTERFACE SPECIFICATION (APP → ONEPIPE)

For details on encryption using the Triple DES Algorithm, read this.

Request (Transact)

{ "request_ref": "{{request_ref}}", "request_type": "reissue_pin", "auth": { "type": card | bank.account | wallet, "secure": {{encrypted auth}}, "auth_provider": "Beeceptor", "route_mode": null }, "transaction": { "mock_mode": "live", "transaction_ref": "{{transaction_ref}}", "transaction_desc": "A random transaction", "transaction_ref_parent": null, "amount": 0, "customer": { "customer_ref": "{{customer_id}}", "firstname": "Uju", "surname": "Usmanu", "email": "ujuusmanu@gmail.com", "mobile_no": "234802343132" }, "meta": { "a_key": "a_meta_value_1", "another_key": "a_meta_value_2" }, "details": null } }

 

Response (when otp_override = false)

{ "status": "PendingValidation", "message": "Please enter the OTP sent to 2348022****08", "data": { "provider_response_code": "900T0", "provider": "Beeceptor", "errors": null, "error": null, "provider_response": null } }

 

Response (when otp_override = true)

{ "status": "Successful", "message": "Transaction processed successfully", "data": { "provider_response_code": "00", "provider": "Beeceptor", "errors": null, "error": null, "provider_response": { "new_pin": "1234", "pin_offset": "1245", "reference": "000022200225154318222333334432", "meta":{ "field_key":"field_value", "field_key":"field_value" } } } }

 

Request (validate with otp)

 

Acceptable values for auth.type

  • Card

  • Bank.account

  • Wallet

Breakdown of the details object

For this service, the details object will be null

 

Possible status response codes

For this service, these are the possible responses a client can receive

Status

Meaning

Status

Meaning

Successful

Standard success code

Failed

Standard failure code

WaitingForOTP

To signify that this provider has requested an OTP from the customer and it should be supplied.

PendingValidation

To signify that this provider needs some extra information to be provided. The response.message will contain the prompt.

 

 

 

INTERFACE SPECIFICATION (ONEPIPE → PROVIDER MICRO SERVICE)

Request payload from OnePipe to the provider microservice comes encrypted, using the Triple DES Algorithm. See details.

Read this closely.