Change PIN
- Ope Adeoye
With this service, the calling apps can change 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) as well as the new PIN they are trying to set it to. OnePipe will in turn forward to the provider’s dedicated implementation. 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_overridesuch 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 |
|---|---|
Invoice | The host client will invoice the calling app periodically for all calls to the endpoint. |
Process flows
Sequence of calls
App calls
/transactwith the right auth details (if supplied)Provider responds with
WaitingForOTPorPendingValidation(if required)App calls
/transact/validateto supply OTP if neededProvider responds with any of the completion codes
SuccessfulorFailed.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": "change_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": {
"new_pin": "1234"
}
}
}
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": {
"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 have the following:
Field | Type | Requirement | Description |
|---|---|---|---|
new_pin | string | compulsory | The new PIN to be attached to the card, account or wallet |
Possible status response codes
For this service, these are the possible responses a client can receive
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 |
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.