Home Integration and API

Integration and API

Find details of our REST APIs and integration resources
By Surafel Araya and 1 other
3 articles

SDK Integration

This guide details how to integrate the YaYa Wallet API into your application using our Software Development Kits (SDKs). API Key and Secret - Log in to your YaYa Wallet account and navigate to your profile page. - Locate the API section and generate a new API key pair. This will provide you with both the API Key and API Secret. - Important: The API Secret is crucial for secure communication. Treat it like a password and store it securely. There's no way to recover a lost secret, so generate a new one if needed. Choose Your SDK - YaYa Wallet offers SDKs in various programming languages to simplify integration with our API. These SDKs allow developers to programmatically interact with the YaYa Wallet platform for various functionalities. Available SDKs: - Node.js: Integrate YaYa Wallet functionalities into your Node.js applications using the official SDK available on Node Package Manager (npm): @yayawallet/node-sdk. - Refer to the detailed instructions provided at this github repo, yayawallet/yayawallet-node-sdk. - Python: Develop Python applications with YaYa Wallet integration using the official SDK available on the Python Package Index (PyPI): yayawallet-python-sdk. - Refer to the detailed instructions provided at this github repo, yayawallet/yayawallet-python-sdk. - Java: Integrate YaYa Wallet functionalities into your Java applications using the SDK available on https://mvnrepository.com. - Refer to the detailed instructions provided at this gihub repo, yayawallet/yayawallet-java-sdk. Next steps Each SDK comes with comprehensive documentation to guide you through the integration process. Refer to the specific SDK documentation linked above for detailed instructions on using the YaYa Wallet SDK in your chosen language.

Last updated on Apr 16, 2024

API Authentication

Before being able to sign any requests, you must create an API key from your profile page in the YaYa Wallet website. Upon creating a key you need to have 2 pieces of information: - API Key - API Secret The API Key and API Secret are generated and provided by YaYa Wallet. Please note that the API Secret can not be recovered once lost. If you lost this information, please create a new API Secret. YaYa REST API uses a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication. To authenticate a request, you first concatenate selected elements of the request to form a string. You then use your YaYa API secret to calculate the HMAC of that string. Informally, we call this process "signing the request," and we call the output of the HMAC algorithm the signature, because it simulates the security properties of a real signature. Finally, you add this signature as a parameter of the request by using the syntax described in this section. These authentication headers are required for all calls to the REST endpoint. - YAYA-API-KEY The API key as a string. - YAYA-API-TIMESTAMP A timestamp for your request. - YAYA-API-SIGN The base64-encoded signature (see Signing a Message section below). The Authorisation fields in the HTTP header are used to pass user credentials. When authentication fails, the error code 401 (Unauthorised) is returned. Signing a Message For the header of YAYA-API-SIGN: 1. Use API-Secret YAYA-API-SECRET to encrypt the pre-hash string {timestamp+method+endpoint+body} with SHA256 HMAC. The request body is a JSON string and needs to be the same with the parameters passed by the API. 2. After that, use base64-encode to encrypt the result in step 1 again. Notice: - The encrypted timestamp shall be consistent with the YAYA-API-TIMESTAMP field in the request header. - The body to be encrypted shall be consistent with the content of the Request Body. - The Method should always be UPPERCASE. - The endpoint needs to contain the complete path string but without the base url. e.g. /api/en/user/profile. - The body is empty string ("") if there is no request body (typically for GET requests). This is a cURL example of getting profile information curl -H "Content-Type:application/json" -H "YAYA-API-KEY:your-api-key" -H "YAYA-API-TIMESTAMP:1673381836197" -H "YAYA-API-SIGN:your-signature" -X POST -d '{"account_name":"12-char-acct"}' {env_base_url}/api/en/user/profile Selecting a Timestamp The YAYA-API-TIMESTAMP header MUST be the number of milliseconds since Unix Epoch in UTC. e.g. 1673381836197000 The difference between your timestamp and the API service time must be less than 5 seconds, or your request will be considered expired and rejected. We recommend using the time endpoint to query for the API server time if you believe there may be a time skew between your server and our API server. curl -X GET {env_base_url}/api/en/time

Last updated on Apr 16, 2024

Webhooks

Use incoming webhooks to get real-time updates Listen for events on your YaYa Wallet account so your integration can automatically trigger reactions. Why to use webhooks? When building YaYa Wallet integrations, you might want your applications to receive transaction information as they occur in your account, so that your backend systems can execute actions accordingly. To enable webhook, you need to register webhook endpoint. After you register your endpoint, YaYa Wallet can push real-time transaction event data to your application’s webhook endpoint when it happen in your YaYa Wallet account. YaYa Wallet uses HTTPS to send webhook events to your app as a JSON payload. Receiving webhook events are particularly useful for listening to asynchronous events, such as when a customer’s confirms a payment request, a customer makes payment to your account, a recurring payment succeeds, or when collecting subscription payments. Structure of a webhook payload The following example payload shows a webhook update information at the end of a transaction. { "id": "1dd2854e-3a79-4548-ae36-97e4a18ebf81", "amount": 100, "currency": "ETB", "created_at_time": 1673381836, "timestamp": 1701272333, "cause": "Testing", "full_name": "Abebe Kebede", "account_name": "abebekebede1", "invoice_url": "https://yayawallet.com/en/invoice/xxxx" } How to set up your webhook integration To start receiving webhook events in your app, create and register a webhook endpoint by following the steps below. 1. Develop a webhook endpoint function to receive transaction data POST requests. 2. Test your webhook endpoint function locally 3. Register your endpoint within YaYa Wallet from the Webhooks section in your web dashboard 4. Secure your webhook endpoint Create a webhook endpoint function Set up an endpoint function that can accept webhook requests with a POST method. Your webhook endpoint function must use HTTPS. Set up your endpoint function so that it: - Handles POST requests with a JSON payload. - Quickly returns a successful status code (2xx) prior to any complex logic that could cause a timeout. For example, you must return a 200 response before updating a customer’s invoice as paid in your accounting system. Register and manage your webhook in YaYa Wallet After testing your webhook endpoint, register the webhook endpoint’s accessible URL using the Webhooks section in the API and Security so YaYa Wallet knows where to deliver events. The registered webhook endpoint must be publicly accessible HTTPS URLs. Secure your webhooks When enabling webhooks, you should set a secret hash. Since webhook URLs are publicly accessible, the secret hash allows you to verify that incoming requests are from YaYa Wallet. You can specify any string value as your secret hash, but we recommend something random. You will use this secret to verify the request sent from YaYa Wallet. After confirming that your webhook endpoint connection works as expected, secure the connection by using webhook signature to verify that YaYa Wallet generated a webhook request and that it didn’t come from a server acting like YaYa Wallet. We will include the signature in our request to your webhook URL, in a header called YAYA-SIGNATURE. The value of YAYA-SIGNATURE header is a HMAC SHA256 signature of the signed_payload using your secret key. The signed_payload is formed by the concatenation of all the values of the payload encoded in UTF-8 format. Verifying YAYA-SIGNATURE header should be done before processing the event. Example to generate the signature in PHP $secret_key = "test_key"; // you may keep this in env variable $data = [ "id"=>"", "amount"=> 100, .... ]; $data_for_seal = implode('', $data); $signed_payload = utf8_encode($data_for_seal); // YAYA-SIGNATURE $signature = hash_hmac('sha256', $signed_payload, $secret_key); Roll endpoint signing secrets periodically The secret used for verifying that events come from YaYa Wallet is modifiable in the Webhooks section of the Dashboard. To keep them safe, we recommend that you change secrets periodically, or when you suspect a compromised secret. Verify events are sent from YaYa Wallet YaYa Wallet sends webhook events from a set list of IP addresses. Only trust events coming from these IP addresses. Additionally, verify webhook signatures to confirm that received events are sent from YaYa Wallet. YaYa Wallet signs webhook events it sends to your endpoints by including a signature in each event’s YAYA-SIGNATURE header. This allows you to verify that the events were sent by YaYa Wallet, not by a third party. Always ensure you verify signatures before processing an event. For verifying signatures, you must complete the following steps: 1. Extract the YAYA-SIGNATURE signature from the header 2. Prepare the signed_payload. The signed_payload string is created by concatenating all the values from the actual JSON payload (that is, the request body) in the order they appear in the payload. For the payload example above, the signed_payload would be the following 1dd2854e-3a79-4548-ae36-97e4a18ebf81100ETB16733818361701272333TestingAbebe Kebedeabebekebede1https://yayawallet.com/en/invoice/xxxx 3. Determine the expected signature. Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message. 4. Compare the signatures. Compare the signature in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance. Preventing replay attacks A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such attacks, YaYa Wallet includes a timestamp in the YAYA-SIGNATURE header. Because this timestamp is part of the signed payload, it’s also verified by the signature, so an attacker can’t change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, you can have your application reject the payload. We recommend a tolerance of 5 minutes between the timestamp and the current time. You can change this tolerance by providing an additional parameter when verifying signatures. Use Network Time Protocol (NTP) to make sure that your server’s clock is accurate and synchronises with the time on YaYa’s servers. YaYa Wallet generates the timestamp and signature each time we send an event to your endpoint. If YaYa Wallet retries an event (for example, your endpoint previously replied with a non-2xx status code), then we generate a new signature and timestamp for the new delivery attempt. Quickly return a 2xx response Your endpoint must quickly return a successful status code (2xx) prior to any complex logic that could cause a timeout. For example, you must return a 200 response before updating a customer’s invoice as paid in your accounting system.

Last updated on Apr 16, 2024