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.

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

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

6. Where the provider supports it, the app can call /transact/reverse to request a reversal

INTERFACE SPECIFICATION (APP → ONEPIPE)

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": "2233305555"
        }
    }
}

Request (validate with otp)

{
  "request_ref":"{{request_ref}}", 
  "request_type":"change_pin",
	"auth": {
        "secure": "{{encrypted_otp}}",
        "auth_provider": "Beeceptor" 
    },
    "transaction": {
        "transaction_ref": "70713093460718"
    }
}

Acceptable values for auth.type

• Card

• Bank.account

• Wallet

Breakdown of the details object

For this service, the details object will have the following:

Possible status response codes

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

INTERFACE SPECIFICATION (ONEPIPE → PROVIDER MICRO SERVICE)

Read this closely.