# Requesting Payments
source: https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/tutorials/requesting-payments-tutorial/index.md

This tutorial guides you through the process of requesting payments from a user Payment Service User (PSU) using the provider Account Servicing Payment Service Provider (ASPSP) of their choice.

#### Prerequisites: {#prerequisites}

* You must have created an App. Make sure you have recorded the `CLIENT_ID` and `CLIENT_SECRET`.
* This tutorial uses `curl` in order to send requests and receive responses.

### Step 1 - The Payment Request {#step-1---the-payment-request}

Create a payment and retrieve a redirect url for users to initiate the payment.

API Reference: `POST /v1/payments/create`

#### Request {#request}

* Create a `USER_HASH` to identify the user.
* Provide an `IBAN` for receiving the payment.
* Specify the `AMOUNT` and `CURRENCY_CODE` (for this tutorial, we are using `SEPA` payments which only allow `EUR`, please refer to the payment schemes for additional details).
* Specify a `REDIRECT_URL` where the user will be redirected after finishing the payment flow.

```shell
curl -X POST \ 
https://api.nordicapigateway.com/v1/payments/create \ 
-H 'Content-Type: application/json' \ 
-H 'X-Client-Id: <CLIENT_ID>' \ 
-H 'X-Client-Secret: <CLIENT_SECRET>' \ 
-d '{
    "userHash": "<USER_HASH>",
    "request": {
        "destination": {
            "iban": {
                "ibanNumber": "<IBAN>"
            }
        },
        "amount": {
            "value": <AMOUNT>,
            "currency": "EUR"
        }
    },
    "redirectUrl": "<REDIRECT_URL>"
}'
```

#### Response {#response}

If the request is successful, the response will look like:

```json
{
  "redirectUrl": "https://app.nordicapigateway.com/start/payment?startToken=<start-token>&paymentId=20220926.azdfqj71oefw3k5hiys7zuk1xr",
  "paymentId": "20190824.xrrksqlmngnw3xisfq8uqd1ijh"
}
```

* Record the `paymentId` for next steps.
* Redirect the user to the `redirectUrl` to start the payment flow.

### Step 2 - User Payment Flow​ {#step-2---user-payment-flow}

Redirect the user to the `redirectUrl` received in the previous step to authorize the payment.
Note: The redirect URL must not be presented in an iframe, and it cannot be reused.

Depending on the parameters passed in the payment request, a flow will be displayed to the user where they will be able to select their provider (if not specified), login, select the account to pay from and complete the payment.

The flow will look like:

![Payment Flow](https://static.developer.mastercard.com/content/open-finance-europe/uploads/tutorials/enterprise-payment-flow.png)

### Step 3 - Payment Result {#step-3---payment-result}

After the payment flow is completed, the PSU is redirected back to the application using the `redirectUrl`. Retrieve the latest state of the payment using the Refresh payment status endpoint.

API Reference: `POST /v1/payments/{paymentId}/refresh-status`

#### Request {#request-1}

* Use the `PAYMENT_ID` retrieved from the first step to get the payment status.

```shell
curl -X POST https://api.nordicapigateway.com/v1/payments/<PAYMENT_ID>/refresh-status \ 
    -H 'X-Client-Id: <CLIENT_ID>' \ 
    -H 'X-Client-Secret: <CLIENT_SECRET>' \ 
    -d '' 
```

#### Response {#response-1}

If the request is successful, the response will look like:

```json
{
  "payment": {
    "paymentId": "20190824.xrrksqlmngnw3xisfq8uqd1ijh",
    "userHash": "<user-hash>",
    "providerId": "DemoBank",
    "providerPaymentId": "<provider-payment-id>",
    "request": {
      "destination": {
        "iban": {
          "ibanNumber": "DK1234567890123456"
        }
      },
      "amount": {
        "value": 1,
        "currency": "EUR"
      },
      "paymentMethod": "SEPA"
    },
    "status": {
      "terminal": true,
      "code": "Succeeded",
      "lastUpdated": "2019-08-24T14:15:22.223+00:00"
    },
    "state": "Preparing",
    "created": "2019-08-24T14:15:22.223+00:00",
    "source": {
      "iban": {
        "ibanNumber": "DK1234567890123456"
      }
    }
  }
}
```

Handle different payment outcomes based on the returned payment status code.

##### Status Codes: {#status-codes}

* ProviderProcessing: ASPSP received the payment request; The service is awaiting confirmation.
* Pending: ASPSP placed the payment in a pending state; further action from the Payer may be required.
* Initiated: ASPSP validated and accepted the payment request, scheduled for the provided date.
* PaymentExecutedDebited: Payment settled on the Payer's account.
* PaymentExecutedCredited: Payment settled on the Payee's account.
* Failed: Authorization of the payment initiation was not successful.
* Cancelled: Payer canceled the payment at the authorization stage or before execution.

Note: Payment initiation status only reflects if the payment order was accepted for execution at the ASPSP, not the actual settlement of the payment.