> For the complete documentation index, see [llms.txt](https://selenium-4.gitbook.io/nexus-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://selenium-4.gitbook.io/nexus-docs/docs/payment-order-initiation/initiate-payment-transaction/main.md).

# Initiate Payment Transaction

| Campo              | Valor                                        |
| ------------------ | -------------------------------------------- |
| **Service Domain** | Payment Order Initiation                     |
| **BIAN Version**   | 14.0.0                                       |
| **Operation**      | Initiate a payment transaction               |
| **Method**         | POST                                         |
| **API Name**       | Payment Order Initiation                     |
| **Versão**         | v1.0.0                                       |
| **Endpoint**       | `POST /v1/payment-order-initiation/initiate` |
| **Autenticação**   | Bearer Token (OAuth 2.0 / OIDC)              |

***

## 1. Descrição da Operação

Esta operação inicia um pedido de transação de pagamento, criando uma ordem de pagamento pendente para processamento e aprovação posterior. O tipo de pagamento é definido através do campo `paymentTransactionType`, permitindo suportar diferentes cenários de negócio utilizando o mesmo contrato base. O serviço captura as identificações da entidade pagadora e beneficiária, os montantes envolvidos e os metadados necessários para processamento da ordem. Esta abordagem está alinhada ao objetivo do Service Domain Payment Initiation, responsável por capturar e validar instruções de pagamento antes da geração e processamento da ordem de pagamento.

***

## 2. Cabeçalhos HTTP

| Header                           | Obrigatório | Notas                                                        |
| -------------------------------- | ----------- | ------------------------------------------------------------ |
| `Authorization: Bearer {token}`  | Sim         | OAuth2 / JWT — `client_credentials` para M2M                 |
| `Content-Type: application/json` | Sim         |                                                              |
| `Accept: application/json`       | Sim         |                                                              |
| `x-request-id`                   | Recomendado | UUID v4 — identificador único do pedido para rastreabilidade |
| `x-channel`                      | Recomendado | Canal de origem (`MOBILE`, `WEB`, `ATM`, `BACKOFFICE`, …)    |

***

## 3. Path Parameters

Sem parâmetros de path.

***

## 4. Payload de Pedido (Request)

```json
{
  "paymentTransactionType": "CRP",
  "amount": {
    "amountValue": "100.00"
  },
  "payeeAccountIdentification": {
    "identifierValue": "1234",
    "identifierType": "PAN",
    "payeeAccountCurrency": {
      "currencyCode": "AKZ"
    }
  },
  "paymentDescription": "Recharge of card ending with 9012",
  "paymentFeesCharges": {
    "feeExemptionIndicator": true
  },
  "payerAccountIdentification": {
    "identifierValue": "5678",
    "identifierType": "CurrentAccount",
    "payerAccountCurrency": {
      "currencyCode": "AKZ"
    }
  }
}
```

### 4.1 Descrição dos campos

| Campo                                                          | Tipo    | Descrição                                                                                                                                                         |
| -------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paymentTransactionType`                                       | String  | Tipo da transação de pagamento. Enum fechado. Atualmente suporta `CRP`. O tipo da transação influencia validações, regras de negócio e obrigatoriedade de campos. |
| `amount`                                                       | Object  | Informações monetárias da transação.                                                                                                                              |
| `amount.amountValue`                                           | String  | Valor monetário da transação. Deve ser positivo e possuir no máximo 2 casas decimais.                                                                             |
| `payeeAccountIdentification`                                   | Object  | Identificação do beneficiário da ordem de pagamento.                                                                                                              |
| `payeeAccountIdentification.identifierValue`                   | String  | Valor do identificador do beneficiário.                                                                                                                           |
| `payeeAccountIdentification.identifierType`                    | String  | Tipo do identificador do beneficiário. Ex.: `PAN`, `CurrentAccount`, `CardID`.                                                                                    |
| `payeeAccountIdentification.payeeAccountCurrency`              | Object  | Moeda associada à conta do beneficiário da transação.                                                                                                             |
| `payeeAccountIdentification.payeeAccountCurrency.currencyCode` | String  | Código da moeda da conta do beneficiário.                                                                                                                         |
| `paymentDescription`                                           | String  | Descrição textual do pedido/transação de pagamento. Campo utilizado para auditoria e rastreabilidade. Limite máximo de 948 caracteres.                            |
| `paymentFeesCharges`                                           | Object  | Configuração de taxas e encargos associados ao pagamento.                                                                                                         |
| `paymentFeesCharges.feeExemptionIndicator`                     | Boolean | Indicador de isenção de taxas. Quando `true`, solicita isenção das taxas aplicáveis.                                                                              |
| `payerAccountIdentification`                                   | Object  | Identificação da origem dos fundos da ordem de pagamento.                                                                                                         |
| `payerAccountIdentification.identifierValue`                   | String  | Valor do identificador da conta pagadora.                                                                                                                         |
| `payerAccountIdentification.identifierType`                    | String  | Tipo do identificador utilizado para localizar a origem dos fundos. Ex.: `CurrentAccount`.                                                                        |
| `payerAccountIdentification.payerAccountCurrency`              | Object  | Moeda associada à conta pagadora.                                                                                                                                 |
| `payerAccountIdentification.payerAccountCurrency.currencyCode` | String  | Código da moeda da conta pagadora.                                                                                                                                |

***

## 5. Payload de Resposta (Response — 201 Created)

```json
{
  "paymentOrderInitiationId": "2026000001",
  "paymentTransactionType": "CRP",
  "paymentOrderInitiationStatus": "Initiated",
  "paymentOrderInitiationDate": "2026-05-28"
}
```

### 5.1 Descrição dos campos

| Campo                          | Tipo   | Descrição                                                  |
| ------------------------------ | ------ | ---------------------------------------------------------- |
| `paymentOrderInitiationId`     | String | Identificador único da ordem/pedido de pagamento iniciado. |
| `paymentTransactionType`       | String | Tipo da transação de pagamento iniciada.                   |
| `paymentOrderInitiationStatus` | String | Estado atual da transação. Inicialmente `Initiated`.       |
| `paymentOrderInitiationDate`   | Date   | Data de criação da ordem de pagamento.                     |

***

## 6. Códigos HTTP de Resposta

| Código                      | Descrição                                                                   |
| --------------------------- | --------------------------------------------------------------------------- |
| `201 Created`               | Pedido de pagamento iniciado com sucesso                                    |
| `400 Bad Request`           | Payload inválido ou campos obrigatórios ausentes                            |
| `401 Unauthorized`          | Token inválido ou ausente                                                   |
| `403 Forbidden`             | Operação não autorizada                                                     |
| `404 Not Found`             | Conta, cartão ou recurso relacionado não encontrado                         |
| `409 Conflict`              | Pedido duplicado                                                            |
| `422 Unprocessable Entity`  | Violação de regra de negócio                                                |
| `500 Internal Server Error` | Erro interno inesperado, incluindo timeout de processamento (`POI-500-001`) |

***

## 7. Envelope Padrão de Erro

### 7.1 Erro de timeout de processamento (500)

Retornado quando o pedido é enviado para processamento assíncrono (fila) e nenhuma resposta é recebida dentro do tempo esperado.

```json
{
  "status": 500,
  "reason": "INTERNAL_SERVER_ERROR",
  "message": "No response received from queue for key d5cd590f-5160-4931",
  "path": "/v1/payment-order-initiation/initiate",
  "errors": [
    {
      "code": "POI-500-001",
      "reason": "PROCESSING_TIMEOUT",
      "message": "Não foi possível processar a sua solicitação dentro do tempo esperado"
    }
  ]
}
```

| Campo              | Descrição                                                                                                 |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
| `status`           | Código HTTP da resposta (`500`).                                                                          |
| `reason`           | Categoria geral do erro (`INTERNAL_SERVER_ERROR`).                                                        |
| `message`          | Mensagem técnica. Contém a chave de correlação do pedido na fila (`key`), útil para diagnóstico nos logs. |
| `path`             | Endpoint invocado.                                                                                        |
| `errors[].code`    | Código de erro do serviço (`POI-500-001`).                                                                |
| `errors[].reason`  | Motivo específico (`PROCESSING_TIMEOUT`).                                                                 |
| `errors[].message` | Mensagem apresentável ao utilizador.                                                                      |

### 7.3 Catálogo de códigos de erro

| Código        | HTTP | Reason               | Descrição                        |
| ------------- | ---- | -------------------- | -------------------------------- |
| `POI-500-001` | 500  | `PROCESSING_TIMEOUT` | Tempo de processamento excedido. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://selenium-4.gitbook.io/nexus-docs/docs/payment-order-initiation/initiate-payment-transaction/main.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.