> 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-orchestration/initiate-payment-orchestration/main.md).

# Initiate Payment Orchestration

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

***

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

Inicia um procedimento de orquestração de pagamentos para processamento de uma transação financeira. Dependendo do tipo de transação, o procedimento poderá executar diretamente a transação ou iniciar um fluxo baseado numa ordem de pagamento que requer uma decisão explícita de aprovação ou rejeição antes da execução financeira.

***

## 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 correlação em logs |
| `x-channel`                      | Recomendado | Canal de origem (`SOP`, `MOBILE`, `BACKOFFICE`, etc.)           |

***

## 3. Path Parameters

Não aplicável.

***

## 4. Payload de Pedido (Request)

### 4.1 Exemplo

```json
{
    "paymentOrchestrationType": "CRP",
    "paymentOrderReference": {
        "paymentOrderIdentifier": "13461782",
        "paymentOrderInitiationDate": "2026-06-16"
    },
    "paymentOrchestrationDecision": "APPROVE"
}
```

### 4.2 Descrição dos Campos

| Campo                                              | Tipo   | Descrição                                                                                                                        |
| -------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `paymentOrchestrationType`                         | String | Tipo do procedimento de orquestração de pagamento a iniciar.                                                                     |
| `paymentOrderReference`                            | Object | Referência da ordem de pagamento associada ao processo de orquestração. Opcional para cenários de execução direta de transações. |
| `paymentOrderReference.paymentOrderIdentifier`     | String | Identificador único da ordem de pagamento.                                                                                       |
| `paymentOrderReference.paymentOrderInitiationDate` | Date   | Data de iniciação da ordem de pagamento.                                                                                         |
| `paymentOrchestrationDecision`                     | String | Decisão a ser aplicada ao processo de orquestração quando o tipo de transação exigir aprovação explícita.                        |

#### Valores Permitidos — `paymentOrchestrationType`

| Valor | Descrição                                      |
| ----- | ---------------------------------------------- |
| `CRP` | Card Recharge Payment (carregamento de cartão) |

#### Valores Permitidos — `paymentOrchestrationDecision`

| Valor     | Descrição                                                               |
| --------- | ----------------------------------------------------------------------- |
| `APPROVE` | Aprova a transação e permite a continuação do processamento financeiro. |
| `REJECT`  | Rejeita a transação e interrompe o processamento financeiro.            |

***

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

```json
{
    "paymentTransactionIdentifier": "123458",
    "paymentTransactionStatus": "CREATED"
}
```

### 5.1 Descrição dos Campos

| Campo                          | Tipo   | Descrição                                             |
| ------------------------------ | ------ | ----------------------------------------------------- |
| `paymentTransactionIdentifier` | String | Identificador único da transação de pagamento criada. |
| `paymentTransactionStatus`     | String | Estado da transação de pagamento.                     |

***

## 6. Códigos HTTP de Resposta

| Código                    | Descrição                                                            |
| ------------------------- | -------------------------------------------------------------------- |
| 201 Created               | Procedimento de orquestração iniciado com sucesso.                   |
| 400 Bad Request           | Pedido inválido ou com dados obrigatórios ausentes.                  |
| 401 Unauthorized          | Credenciais inválidas ou ausentes.                                   |
| 403 Forbidden             | Operação não autorizada.                                             |
| 404 Not Found             | Ordem de pagamento não encontrada.                                   |
| 409 Conflict              | Já existe um procedimento ativo para a ordem de pagamento informada. |
| 422 Unprocessable Entity  | Violação de regra de negócio.                                        |
| 500 Internal Server Error | Erro interno durante o processamento.                                |

***

## 7. Envelope Padrão de Erro

```json
{
  "error": {
    "status": 422,
    "reason": "BUSINESS_RULE_VIOLATION",
    "message": "Saldo insuficiente na conta de despesas para liquidar comissões.",
    "path": "POST /v1/payment-orchestration/initiate",
    "errordetail": [
      {
        "code": "ML-422-001",
        "reason": "INSUFFICIENT_FUNDS_EXPENSE_ACCOUNT",
        "message": "Conta 125818810007: saldo 850.00 USD < despesa 1250.75 USD."
      }
    ]
  }
}
```

***

## 8. Regras de Negócio

1. O valor de `paymentOrchestrationType` deve corresponder a um tipo de orquestração suportado pelo sistema.
2. Atualmente apenas o tipo `CRP (Card Recharge Payment)` é suportado.
3. `paymentOrchestrationDecision` deve conter um dos valores permitidos: `APPROVE` ou `REJECT`.
4. Quando informada, a ordem de pagamento referenciada deve existir no sistema.
5. Quando informada, a ordem de pagamento deve encontrar-se num estado elegível para processamento.
6. Apenas um procedimento de orquestração ativo pode existir para a mesma ordem de pagamento.
7. A decisão `APPROVE` poderá desencadear a execução efetiva da transação e os respetivos processos de liquidação.
8. A decisão `REJECT` termina o fluxo de processamento sem execução financeira.
9. O sistema poderá iniciar a orquestração diretamente sobre uma transação sem ordem de pagamento associada, desde que o tipo de operação o permita.


---

# 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-orchestration/initiate-payment-orchestration/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.