# Setu dev rel challenge - API Specs

**If the spec is not implemented exactly as mentioned in this document, it will result in disqualfication. Your API will be tested using an automated test suite.**

## Product note

- UPI apps like PhonePe will be integrating with your bill system to allow your customers pay their bills using the UPI app.
- You need to expose 2 APIs for UPI App to be able to
- query your system and get outstanding balance for a customer
- update your system when a payment happens.

See the flow diagram here: https://i.imgur.com/llEmzuK.png

# API specs

### Security

The API **should require** an API key in the `X-API-KEY` http header.

### Error response

In case of an error API should send the following error response

{
    "status": "ERROR",
    "errorCode": "customer-not-found"
}

Following error codes are defined

<table>
<tbody>
<tr>
<td><b>Error code</b></td>
<td><b>HTTP Status Code</b></td>
</tr>
<tr>
<td>
auth-error
</td>
<td>403</td>
</tr>
<tr>
<td>invalid-api-parameters</td>
<td>400</td>
</tr>
<tr>
<td>customer-not-found</td>
<td>404</td>
</tr>
<tr>
<td>invalid-ref-id</td>
<td>404</td>
</tr>
<tr>
<td>amount-mismatch</td>
<td>400</td>
</tr>
<tr>
<td>path-not-found</td>
<td>404</td>
</tr>
<tr>
<td>unhandled-error</td>
<td>500</td>
</tr>
</tbody>
</table>

As mentioned above, HTTP status code for error responses should be non `200` codes as defined against each error code above.

## Success responses

- All success responses should have a HTTP status code as 200

## Fetch Bill

URL: `https://example.com/api/v1/fetch-bill`
HTTP method: `POST`

### Request

In the request we will send over customer's mobile number

{
    "mobileNumber": "9898000012"
}

### Response

API is expected to respond with the name of the customer, due Date, due amount and a reference ID.

{
    "status": "SUCCESS",
    "data": {
        
        "customerName": "Ashok Kumar",
        "dueAmount": "2000",
        "dueDate": "2020-06-05",
        "refID": "AX0812878"
    }
}

1. `customerName`: The name of the customer
2. `dueAmount`: the amount to be paid by the customer. This should be a **string** containing the amount in rupees. It should be 0 if customer does not have any dues to be paid. It can not be negative.
3. `refID`: This reference ID would be used in the second API to inform about the payment made by the customer.
4. `dueDate`: Due date in `YYYY-MM-DD` format

In case error send the appropriate error response in the format described previously.

1. `auth-error`
2. `invalid-api-parameters`
3. `customer-not-found`

## Bill Payment Update

URL: `https://example.com/api/v1/payment-update`
HTTP method: `POST`

### Request

Request will consist of the ref ID from the previous API and transaction related information.

{
    "refID": "AX0812878"
    "transaction": {
        "amountPaid": "2000",
        "date": "2020-06-05",
        "id": "OUAB012344"
    }
    
}

### Response

{
    "status": "SUCCESS",
    "data": {       
        "ackID": "AX091283"
    }
}

1. `ackID`: This is the acknowledgement ID from your system for payment.

Note that this API is expected to be **idempotent.** If we send you the same payload, you need to respond with the same response. Multiple identical requests have the same effect as making a single request. This API might be retried in case of network errors and you need to make sure you are not treating it as a duplicate transaction if you see the same transaction ID and ref ID.

Also note that refID is for one time use only. If you see two transactionIDs against the same refID, you should reject the request with `invalid-ref-id` error response.

In case error send the appropriate error response in the format described previously.

1. `auth-error`
2. `invalid-api-parameters`
4. `invalid-ref-id`
5. `amount-mismatch`