# Collect For Payment

The request takes the PRN to be paid for as a mandatory parameter. The requesting merchant account chooses which transaction method to work with; [Mobile Money](https://apidoc.govbill.ug/collections/request-mobile-money-payment) or [Card](https://apidoc.govbill.ug/collections/request-card-payment) as described in the respective sections and as part of the request payload, the **prn** parameter is added.

The GovBill platform will go ahead to process the funds collection and when successful, it will automatically proceed to make the PRN payment and execute a second webhook for the PRN payment confirmation. However, in the event the PRN is not eligible to payment (invalid, already paid, expired etc), the merchant account will be notified via callback even before the collection process happens. The merchant account account required to have profiled a **service payments callback URL** as this will be the URL notified for everything regarding PRN payment.

## Step 1: Form the request payload

Majority of the parameters depend on the method one decides to use for the collection and in addition, the PRN parameter is included and described in the table below;

<table><thead><tr><th width="137">Parameter</th><th width="102">Type</th><th width="110">Required</th><th>Description</th></tr></thead><tbody><tr><td>prn</td><td>String</td><td>true</td><td>The PRN to be paid for on completion of this transaction</td></tr></tbody></table>

After collecting the necessary collection information from your customer, prepare your request payload as demonstrated below. Two (mobile money and card) sample payloads are shared

{% tabs %}
{% tab title="Using Mobile Money" %}

```json
{
    "merchant_reference": "auto",
    "transaction_method": "MOBILE_MONEY",
    "currency": "UGX",
    "amount": 25000,
    "provider_code": "mtn_momo_ug",
    "msisdn": "256772000001",
    "customer_email": "johndoes@gmail.com",
    "customer_name": "JOHN DOE",
    "description": "PRN Payment",
    "prn": "2250000001301"
}
```

{% endtab %}

{% tab title="Using Card" %}

```json
{
    "merchant_reference": "auto",
    "transaction_method": "CARD",
    "currency": "UGX",
    "amount": 25000,
    "provider_code": "card_ug",
    "customer_email": "johndoes@gmail.com",
    "customer_name": "JOHN DOE",
    "description": "PRN Payment",
    "prn": "2250000001301",
    "require_confirmation": false
}
```

{% endtab %}
{% endtabs %}

<mark style="color:green;">`POST`</mark> `https://gwapisdbx.govbill.ug/v1/collections/collect-for-payment`

The request is sent as a JSON body as demonstrated by the sample request below. Sample responses (acknowledgement and failure) are also shared.

```powershell
curl -X POST "https://gwapisdbx.govbill.ug/v1/collections/collect-for-payment" \
   -H 'Content-Type: application/json' \
   -H "x-api-version: 1" \
   -H "public-key: your-public-key" \
   -d '{
        "merchant_reference": "auto",
        "transaction_method": "CARD",
        "currency": "UGX",
        "amount": 25000,
        "provider_code": "card_ug",
        "customer_email": "johndoe@gmail.com",
        "customer_name": "JOHN DOE",
        "description": "PRN Payment",
        "prn": "2250000001301"
    }'
```

{% tabs %}
{% tab title="202: Accepted - Request acknowledged for processing" %}

```json
{
	"code": 202,
	"status": "accepted",
	"message": "Request Accepted",
	"data": {
		"internal_reference": "GOVBILBJQT2KHDM6FZMJMH",
		"merchant_reference": "MCTREFPFYRECCFQ6RDMAWQZXVE"
	}
}
```

{% endtab %}

{% tab title="400: Bad Request - Request is not formed as expected" %}

```json
{
    "code": 400,
    "status": "error",
    "message": "256752000001 is not a valid MTN Mobile Money Uganda (mtn_momo_ug) phone number",
    "data": {
        "internal_reference": "GOVNETQJ7CA7ESLZCRBXSX"
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
As of this point in time, the collection leg of the process is the one underway and the merchant handles any response/callback just like they would based on the collection method selected. When the collection succeeds however, an extra step comes up and described below.
{% endhint %}

## Step 2: Payment confirmation notification

If the collection happened successfully, the GovBill platform automatically proceeds to make the PRN payment using the collected funds. When the PRN payment is successful, a confirmation webhook will be sent to the designated service payment callback URL. The callback structure is  as shared below. The paid PRN would be in the **account\_number** parameter of the callback payload.

```json
{
    "event": "payment.completed",
    "payload": {
        "merchant_reference": "MCTREFWZ6QBEBZT5BZ6N",
        "internal_reference": "GOVBILLW9HWCZ9FBEVW6",
        "transaction_type": "SERVICE_PAYMENT",
        "request_currency": "UGX",
        "request_amount": 25000,
        "transaction_status": "COMPLETED",
        "account_number": "2250000001301",
        "transaction_charge": 1000,
        "transaction_amount": 26000,
        "customer_name": "JOHN DOE",
        "service_name": "URA Payment",
        "status_message": "Transaction completed successfully",
        "additional_details": {}
    }
}
```