API Documentation
API ReferenceDeveloper ConsoleDeveloper Community

Bank Deposits

Learn how deposits by Liquidity Providers and Payment Gateways are being handled in PIPE

1. Overview

PIPEChain allows the use of Unique codes for participants during onboarding. This unique code follows the prefix LP and PG for liquidity providers and Payment Gateways, respectively. This unique code is added to the transaction memo during deposit to allow for easy mapping of all participants

2. Endpoints


EnvironmentResourceEndpoint
stagingAuthentication Tokenhttps://id.pipechain-testnet.stargate.is/realms/interswitch-dev/protocol/openid-connect/token
stagingApihttps://dev-api-pipechain.qa.interswitchng.com

3. API Calls

3.1 Create bank deposits

The Payment Gateways call this endpoint to initiate successful bank deposits by participants

POST /v2/bank-deposits

{

"transactionId": “[string] Unique transaction id generated by the payment gateway or liquidity provider.”,

"transactionAmount": “[string] Amount deposited by the participant.”,

"transactionMemo": “[string] Memo or additional information about the transaction.”,

"direction": “[string] Indicates whether it’s a credit or debit transaction.”,

"currency": “[string] Three-letter currency used for the deposit.”,

}

3.2 History of bank deposits

Retrieve the transaction history for a bank deposit made using a specific TransactionID by using this endpoint.

GET /v2/bank-deposits/:TransactionID

4. Try it out:

You will need to obtain the value for the X_INTERSTELLAR_ERM_API_KEY header required below. Kindly contact the product owner to get or generate this API key for you. See the section on API Keys for more details

For this demo, use the following:


export X_INTERSTELLAR_ERM_API_KEY=ocQPTBQUdhpCOeBznkJc8sM2rVu4iTFg

4.1 Task

The fictive bank, ng.bank.demo.ngnwants to acknowledge the deposit of 100,000 Naira for pre-funding from a fictive fintech, ng.wallet.demo.ngn.


4.1 Tools you might need

These are the tools you might need to follow along with this tutorial.

  • linux or mac: Many of the command line examples have been customized for UNIX-like operating systems.

  • curl: To perform API calls.

    • mac: brew install curl
    • ubuntu/debian:.sudo apt-get install curl

  • jq: To process JSON on the command line.

    • mac: brew install jq
    • ubuntu/debian:.sudo apt-get install jq

  • jo: To create JSON on the command line.

    • mac: brew install jo
    • ubuntu/debian:.sudo apt-get install jo

  • openssl: To perform cryptographic operations on the command line.

    • mac: brew install openssl
    • ubuntu/debian:.sudo apt-get install openssl

    4.2 RSA Keys

    Depositing funds requires digital signatures as outlined in our Security Prologue

To facilitate our command-line operations for this tutorial, we will store our payment gateway RSA keys in special folders.

mkdir -p ~/.demo-rsa-keys

The private and public keys of each payment gateway you manage should be kept inside the above folder with the format below:

  • ~/.demo-rsa-keys/paymentGatewayId.pub for the public key, and
  • ~/.demo-rsa-keys/paymentGatewayId.priv for the private key

e.g.

  • ~/.demo-rsa-keys/ng.bank.demo.ngn.pub for the public key, and
  • ~/.demo-rsa-keys/ng.bank.demo.ngn.priv for the private key

4.3 RSA Keys for our fictive banks.

For this demo, we have created two fictive payment gateways:

  • ng.bank.demo.ngn: A fictive bank in Nigeria that serves NGN.
  • ng.wallet.demo.ngn: A fictive fintech in Nigeria that serves NGN.

Use the commands below to create their private and public RSA keys in the right folder for this demo.

Commands to setup demo RSA keys

Create the folder where we will store our keys for the purpose of this demo.

mkdir -p ~/.demo-rsa-keys

Store the RSA private key for the fictive bank in Nigeria: ng.bank.demo.ngn.priv.

cat <<'EOT' >> ~/.demo-rsa-keys/ng.bank.demo.ngn.priv
-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEAsur+OS6AovTYetVlI/Dnt6j3SEWyRaT4mnTIjKsBAh9sdgvg
IR69GbbWSLYD3amhTaokXqNJEKEL2PwSMdrFCvCUybgVAU3LkT0bcBsnwk7WlhT+
3oH2BMpPltYGz709xedqikoCt248WdBbmlUavJDe2zp759nab2av4i9yjBaD9nmC
62/ClOM9VqonH5IHgw4dNI3XCrk4QUD7kw+jtYXW4WfSAn52y06pmbuE1Oun7fBy
mhKdlV+px5FQWGHo75HC0CMnHCvCjwe6DOl4CA7oqDU765FQL/iytFzE8OtDnhsn
Ri3jSyjP/6TNOkE1NW2ei14yYD66JCkLu+5OgQIDAQABAoIBADe4/mJavE+ESCPB
cFWIQvKtWg6VPld4cMDSHF/LJm490S7WtgA6rZRjoEtW/M89dHJWyir7WdcnASSc
JSKHyxSEJyLIBSq5yuu6B2Cb5H8cxLJLabFs8m09gRouIEL04ldPopvdPwlX+M3U
GaNwW/pceDv48/wamnBVn/Om6Vr9Zs8/7Ar/A8ifqDPSlygQ8hmu+5nm6QUe0sp4
9xc6QD0SxHS7XbsOt/PryFSFHHWUQWzSAMs9D91gZ+WkRNHUjoW7qsPMBJvEubIn
pn95P8vGl+jsCzTVIW+S751FqI+VKQF7LQaKqT13yLh+ygvT9Uq/649YH5h+6qpR
GxtW210CgYEA3JOzVrRgOkyHtrn+l/B8AB2Uz3S46zJWuIFedfUuckxLIEY9qlop
HF50W5oM4CTKhcxx3sBLUldqkTfjXLK0O/2XfHGPO7kHUb/SsEVrsJ6etVYiXKYK
SZye2sAPYrp2p2rJLVdDHtd9cGGYS+fFz2ztfn76YbgMKwnCoudD28MCgYEAz6ae
WO3jb8EotO/j/+46j/lCGgbKFfMAW2LGMcgnwy+FuM6qV/CfEF4hp4i9CsX4FRxs
CEo78rnPDUXKffyt6NF9phYMdUEi14tmPu6J3cY/AErP9SWXM6swagTRJ5mHwTrO
QEyC5SkRWiuoNeKkhatWSvorg31CSPOMB+x1fGsCgYEAmMnmq+R902Q3jacAZ5a5
DgtvjNQ5UxGnaF6UY/jVl26pi02cYWfamkADMYBf8tMJRez742QnyH2s37Jq10ch
+XwLdrPil2fvXf0Vn+w2UD1PiiSD4NFSxvKqRrRK9ARdNFKPz8xmPfLefP3dVJbT
On8lcz3Zid7G7vjvzY+MPakCgYEAlEo29ucb7ukQevZ96n1kkQC+dfu3QamB7cFC
LLb1vmwnoOzltVt/HJ88hXofFpx+KAVeGSV6XkLXXHEkxIg4YfWJN5yzVOEpUqiY
YgTTq+8xerHyhO1NZ3avYmcCPrdjvViThlOdfq2vWKeovqKWP2c2fuDdRk+jkJls
vRPeavUCgYEAnn39g1CFuL0e+goUZ4SkS6dz1PEmahCgDgKSCNcdXc49+badyWhg
aGpZpH4Emds96mUZJLpgxqvj+it+UsGZvCr2IBeYZ/btmareMcwMxrI6JLXqeyGA
p+7WTj2m1IY461InDW4Rv30HHNhIWxrjoA5ngtuY0ro2bhwo77iygCc=
-----END RSA PRIVATE KEY-----
EOT

Store the RSA public key for the fictive bank in Nigeria: ng.bank.demo.ngn.pub.

cat <<'EOT' >> ~/.demo-rsa-keys/ng.bank.demo.ngn.pub
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsur+OS6AovTYetVlI/Dn
t6j3SEWyRaT4mnTIjKsBAh9sdgvgIR69GbbWSLYD3amhTaokXqNJEKEL2PwSMdrF
CvCUybgVAU3LkT0bcBsnwk7WlhT+3oH2BMpPltYGz709xedqikoCt248WdBbmlUa
vJDe2zp759nab2av4i9yjBaD9nmC62/ClOM9VqonH5IHgw4dNI3XCrk4QUD7kw+j
tYXW4WfSAn52y06pmbuE1Oun7fBymhKdlV+px5FQWGHo75HC0CMnHCvCjwe6DOl4
CA7oqDU765FQL/iytFzE8OtDnhsnRi3jSyjP/6TNOkE1NW2ei14yYD66JCkLu+5O
gQIDAQAB
-----END PUBLIC KEY-----
EOT

Store the RSA private key for the other fictive fintech in Nigeria: ng.wallet.demo.ngn.priv.

cat <<'EOT' >> ~/.demo-rsa-keys/ng.wallet.demo.ngn.priv
-----BEGIN RSA PRIVATE KEY-----
MIIEogIBAAKCAQEAjOWUt8L5ELgVPLXeFAZFisu1NvxwtQchgU9mY4fec1sfgj9N
nBWYc461W3FduSCuBAqfhxGiVPq9A5d2BNbJ45/YXNREgSHazHZpAWrF2qVzwoJj
DdkeOiMZjcIKWDCY8VHtjjVQg4orl909Sc2R+iwMYUPRI0iFlmx3ucgH3Hlerexo
B9cOVcz6M/zeedkBtvA3QqJG3IDyOJwJeA7PpK3BapdmQKMHr++LtypuL13q6Sef
D0ycix4pep/W+A1f2BhgizGgDKETqk4e8WuLbxKv2HAo+VotBRJlqyrBg92CeQvs
FIFBwv29h8fpdVxvpRZ0gxfmHTX8ybMJ0ykYBwIDAQABAoIBAGniQnAS2yAAZx1X
w4wi5nIXAplO/thcgoZuCBE2Uys3yKcWMZnh9M6q6YnN2VQ9xeiNnzNfQjJAuHkR
gwTB8bjZMD0a3Fx697X+Ko2BEy1sd2EuoYgPqZKhPBv3PdTmuJlqK29ai6Y+2OHo
xp1HGrP6FFeoImw0nQfdfeAk/htmDugjKn4XS04Up++s6lb64g2JJTPakDkZ+z6L
xcmivcoSEnZcMT/PrkEVJ5YDWkwtOS0qN68DHoNzK9rFlFW1Gc5IDvpu9PjagGlQ
Jh9GcAs93iQ9wN3qK6Btl2MRZG+TmNDnpREPEsUPev9GJbCEpJgq2CYSFNLRB/mG
GNC+tBkCgYEA1uz7rq8xRRZWCs2iLQ1Twcn22DX4tSNWypE54WtR813E3TdZry2B
TDVCshYzlEmBljfp2Rjqo6YqhXWXnpwk+2i/0nDsUbKdRallto5nAVAQZpQr3fGv
MUgbM1UEhPuDl0gC4+2vY0yakM6n7XOeXMuu9G3HvHRcgtCmWGIJGcsCgYEAp9LP
aa63Bn9iB319oLlFYNDKTlVIb7R8S4GG/J1Boz87s3UhiMr9sKSUCDNkw3oMj1p5
/HNQe+CnnCZ/t+8T7U2YzfYFasD0wr2hBJ3lbxFiwwKuQEBVtvuemZlb4DQACQOn
0PupRPVcCajdglTtZ6CcMyfCWEJKjUewDMJAIzUCgYBOV8oSTdgG1/J7M6PHClGa
lRT+kQXceUo8wp03lxgjPu3wuSle2paEAfIS2lbo2bZ73FvIf/Wfu4VKaqfe8Anm
/rLVccYirZn4d5wU5GmVp+qiiaZH275Bl4gauQXRt6Cq91veW5iP+K9q03mQ65Ex
QCnA/XdOMZg7MvU/yFSK6wKBgHBumSpSNKgTuxcNiZadyM8d0gs8s3Sy0/q54jdn
G0xE1rhZpofAhslK2SnNVJppL/TyRntMvgTf8yp32GTftNfsfoytX9+vOcslw7QW
HFmWqjW/nAHLmCEo3Y5F4fmInOVtH4awsyxRvMFz8kKYpxwfy8Wxw0/hyZRxDI7f
rJxpAoGAFhYlw0EI24TJO8NXUSe+dEEGlo0x300kbn9m6yxMZiCJvO/Ak1YkxGXP
f/PZOt62HXpi/md64/arv+l3I0/QfMQhVgZKJYla5FLxXzSVu63Co6NzRIt38RqT
q0b1BRHNF5zzkP0u/cwxK5M0VqGcCNit0hdBBl9+wtSSeBnIJ3Y=
-----END RSA PRIVATE KEY-----
EOT

Store the RSA public key for the other fictive bank in Nigeria: ng.wallet.demo.ngn.pub.

cat <<'EOT' >> ~/.demo-rsa-keys/ng.wallet.demo.ngn.pub
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAjOWUt8L5ELgVPLXeFAZF
isu1NvxwtQchgU9mY4fec1sfgj9NnBWYc461W3FduSCuBAqfhxGiVPq9A5d2BNbJ
45/YXNREgSHazHZpAWrF2qVzwoJjDdkeOiMZjcIKWDCY8VHtjjVQg4orl909Sc2R
+iwMYUPRI0iFlmx3ucgH3HlerexoB9cOVcz6M/zeedkBtvA3QqJG3IDyOJwJeA7P
pK3BapdmQKMHr++LtypuL13q6SefD0ycix4pep/W+A1f2BhgizGgDKETqk4e8WuL
bxKv2HAo+VotBRJlqyrBg92CeQvsFIFBwv29h8fpdVxvpRZ0gxfmHTX8ybMJ0ykY
BwIDAQAB
-----END PUBLIC KEY-----
EOT

4.4 Get Token

export TOKEN_ENDPOINT=https://id.pipechain-testnet.stargate.is/realms/interswitch-dev/protocol/openid-connect/token\;

export TOKEN_CLIENT_ID=interswitch-dev-api;

export API_ENDPOINT=https://dev-api-pipechain.qa.interswitchng.com
export MY_USERNAME="ng.bank.demo.ngn.api";
export MY_PASSWORD="abc";
export MY_TOKENS=`curl -s --request POST \
--url "$TOKEN_ENDPOINT" \
--data-urlencode grant_type='password' \
--data-urlencode username="$MY_USERNAME" \
--data-urlencode password="$MY_PASSWORD" \
--data-urlencode client_id="$TOKEN_CLIENT_ID"`

echo $MY_TOKENS


export MY_ACCESS_TOKEN=`echo $MY_TOKENS | jq -r ".access_token"`

echo $MY_ACCESS_TOKEN

4.5 Get Participants Bank Transaction Memo

Let's get the liquidity provider bank transaction memo for the liquidity provider test-liquidty-provider.

curl -s --request GET \
--url "$API_ENDPOINT/v2/liquidity-providers/test-liquidty-provider" \
--header  "accept: application/json" \
--header 'accept: */*' \
--header "X_INTERSTELLAR_ERM_API_KEY: $X_INTERSTELLAR_ERM_API_KEY" \
--header "Authorization: Bearer $MY_ACCESS_TOKEN"

Note the bankTransactionMemo returned and set it in.

bankTransactionMemo="LPBB4C41"

4.5 Set API Path for Bank Deposit

export API_PATH="/v2/bank-deposits"
echo $API_PATH

4.6 Construct JSON Payload

We will use a Linux tool called jo to create a JSON payload with the following fields.

fieldtypedescription
transactionIdstringUnique transaction ID generated by the payment gateway
transactionAmountstringAmount deposited by the non-liquidity gateway
transactionMemo string Memo or additional information about the transaction
direction stringIndicates whether it's a credit or debit transaction
currencystringThree-letter currency used for the deposit

export TRANSACTION_ID=$(date +%s)

export API_PAYLOAD=`jo -p -- \
  -s transactionId="$TRANSACTION_ID" \
  -s transactionAmount="100000" \
  transactionMemo="LP0CD012" \
  direction="credit" \
  currency="NGN"`

echo $API_PAYLOAD

4.8 Get Signature



export PAYLOAD_SIGNATURE=`echo -n "$API_PATH$API_PAYLOAD" | openssl dgst -sha256 -sign ~/.demo-rsa-keys/ng.bank.tutorialsv2.ngn.priv | openssl enc -base64 -A`

echo $PAYLOAD_SIGNATURE

4.9 Perform deposit

curl -s --request POST \
--url "$API_ENDPOINT$API_PATH" \
--data "$API_PAYLOAD" \
--header  "accept: application/json" \
--header "X-PAPE-SIGNATURE-BASE64: $PAYLOAD_SIGNATURE" \
--header 'accept: */*' \
--header "Content-Type: application/json" \
--header "X_INTERSTELLAR_ERM_API_KEY: $X_INTERSTELLAR_ERM_API_KEY" \
--header "Authorization: Bearer $MY_ACCESS_TOKEN"

4.10 Get deposit status

curl -s --request GET \
--url "$API_ENDPOINT$API_PATH/$TRANSACTION_ID" \
--header 'accept: */*' \
--header "Content-Type: application/json" \
--header "X_INTERSTELLAR_ERM_API_KEY: $X_INTERSTELLAR_ERM_API_KEY" \
--header "Authorization: Bearer $MY_ACCESS_TOKEN"

5. Data Models.

5.1 Bank Deposit

fieldtypedescription
transactionIdstringUnique transaction ID generated by the payment gateway or liquidity provider
transactionAmountstringAmount deposited by the participant
transactionMemo string Memo or additional information about the transaction
direction stringIndicates whether it's a credit or debit transaction
currencystringThree-letter currency used for the deposit
beneficiarystringName of Payment Gateway or Liquidity Provider credited