Pagamento de fornecedores(PagFor)

A jornada de PagFor via API do BTG Pactual Empresas oferece a capacidade de automatizar o pagamento de seus fornecedores e permití-los antecipar estes recebimentos, diferente dos métodos normais de pagamento oferecidos pela API.

Ao utilizar o Pagfor, a jornada de pagamento se mantém a mesma:

A API de pagamento é utilizada para criar uma iniciação de pagamento;
No internet banking ou aplicativo, um ou mais usuários(respeitando firmas e poderes) aprova o pagamento.

A partir deste ponto, o pagamento transforma-se em um recebível para o recebedor do pagamento(neste caso, um fornecedor) e encontrará-se disponível para antecípação no painel de antecipação de fornecedores.

Utilização

A modalidade de PagFor está disponível somente para os seguintes tipos de pagamento:

Tipo
BANKSLIP
PIX_MANUAL
TED
TEF

Para realizar um pagamento PagFor, é preciso ajustar o payload para atender alguns requisitos:

1- É preciso incluir, na root do objeto de pagamento, o agreementId previamente acordado entre integrador e BTG Pactual Empresas.

1- É necessário que o payload do pagamento possua as instruções de PagFor dentro do objeto detail conforme:

...

"detail": {
    ...

    "products": {
    "anticipation": {
      "invoiceNumber": "01951951095",
      "paymentExternalId": "id" # Nullable
    }
  }

    ...
}

...

Máquina de estados

Caso o recebível seja antecipado pelo fornecedor, será gerada uma posição de crédito atrelada ao pagamento e que será paga no paymentDate informado no payload. Neste cenário, o pagamento entrará na seguinte máquina de estados:

Onde:

Status	Descrição
STARTED	Pagamento aguardando aprovação
SCHEDULED	Pagamento agendado
CANCELED	Pagamento cancelado
FAILED	Falha no pagamento
RETAINED	Pagamento retido por pendência de autenticação por fraude
ANTICIPATION_STARTED	Ordem de antecipação disparada
ANTICIPATED	Ordem de antecipação confirmada
ANTICIPATION_CONFIRMED	Posição de crédito da antecipação paga

Caso o recebível não seja antecipado pelo fornecedor, o pagamento seguirá o fluxo de um pagamento comum.

Eventos de webhook

Abaixo estarão listados os eventos únicos referentes ao Pagfor. Os demais eventos podem ser consultado em Pagamentos

payments.anticipation-started

{
	"paymentId": "585c1339-eb6d-4a95-a948-ee240df3038d",
	"type": "TED",
	"amount": 1,
	"batchId": "e4c40b06-5347-480e-90d4-7784e98cc6f5",
	"scheduledDate": "2026-02-23",
	"paymentDate": "2026-02-23",
	"status": "ANTICIPATION_STARTED",
	"debitParty": {
		"taxId": "1111111111",
		"name": "TESTE S.A..",
		"number": "0033333",
		"branchCode": "50",
		"bankCode": "208"
	},
	"detail": {
		"creditParty": {
			"account": {
				"bankCode": "341",
				"branch": "8562",
				"ispb": "40404440",
				"number": "000033344",
				"type": "CC"
			},
			"name": "TESTE LTDA",
			"taxId": "04444004000404"
		},
		"products": {
			"anticipation": {
				"anticipationDate": "2026-02-13T00:00:00",
				"creditParty": {
					"account": {
						"bankCode": "341",
						"branch": "8562",
						"number": "000044444",
						"type": "CC"
					},
					"name": "TESTE LTDA",
					"taxId": "04444004000404"
				},
				"invoiceNumber": "0000693821",
				"paymentExternalId": "3008332290"
			}
		}
	},
	"authenticationCode": null,
	"tags": {
		"INTERNAL_INVOICE_NUMBER": "0000693821",
		"INTERNAL_PAYMENT_EXTERNAL_ID": "3008332290",
		"externalId": "d1585450-f3ec-4354-b5d3-2ba0a81dcf3f"
	}
}

payments.anticipated

{
	"paymentId": "585c1339-eb6d-4a95-a948-ee240df3038d",
	"type": "TED",
	"amount": 1,
	"batchId": "e4c40b06-5347-480e-90d4-7784e98cc6f5",
	"scheduledDate": "2026-02-23",
	"paymentDate": "2026-02-23",
	"status": "ANTICIPATED",
	"debitParty": {
		"taxId": "1111111111",
		"name": "TESTE S.A..",
		"number": "0033333",
		"branchCode": "50",
		"bankCode": "208"
	},
	"detail": {
		"creditParty": {
			"account": {
				"bankCode": "341",
				"branch": "8562",
				"ispb": "40404440",
				"number": "000033344",
				"type": "CC"
			},
			"name": "TESTE LTDA",
			"taxId": "04444004000404"
		},
		"products": {
			"anticipation": {
				"anticipationDate": "2026-02-13T00:00:00",
				"creditParty": {
					"account": {
						"bankCode": "341",
						"branch": "8562",
						"number": "000044444",
						"type": "CC"
					},
					"name": "TESTE LTDA",
					"taxId": "04444004000404"
				},
				"invoiceNumber": "0000693821",
				"paymentExternalId": "3008332290"
			}
		}
	},
	"authenticationCode": null,
	"tags": {
		"INTERNAL_INVOICE_NUMBER": "0000693821",
		"INTERNAL_PAYMENT_EXTERNAL_ID": "3008332290",
		"externalId": "d1585450-f3ec-4354-b5d3-2ba0a81dcf3f"
	}
}

payments.anticipation-confirmed

{
	"paymentId": "585c1339-eb6d-4a95-a948-ee240df3038d",
	"type": "TED",
	"amount": 1,
	"batchId": "e4c40b06-5347-480e-90d4-7784e98cc6f5",
	"scheduledDate": "2026-02-23",
	"paymentDate": "2026-02-23",
	"status": "ANTICIPATION_CONFIRMED",
	"debitParty": {
		"taxId": "1111111111",
		"name": "TESTE S.A..",
		"number": "0033333",
		"branchCode": "50",
		"bankCode": "208"
	},
	"detail": {
		"creditParty": {
			"account": {
				"bankCode": "341",
				"branch": "8562",
				"ispb": "40404440",
				"number": "000033344",
				"type": "CC"
			},
			"name": "TESTE LTDA",
			"taxId": "04444004000404"
		},
		"products": {
			"anticipation": {
				"anticipationDate": "2026-02-13T00:00:00",
				"creditParty": {
					"account": {
						"bankCode": "341",
						"branch": "8562",
						"number": "000044444",
						"type": "CC"
					},
					"name": "TESTE LTDA",
					"taxId": "04444004000404"
				},
				"invoiceNumber": "0000693821",
				"paymentExternalId": "3008332290"
			}
		}
	},
	"authenticationCode": null,
	"tags": {
		"INTERNAL_INVOICE_NUMBER": "0000693821",
		"INTERNAL_PAYMENT_EXTERNAL_ID": "3008332290",
		"externalId": "d1585450-f3ec-4354-b5d3-2ba0a81dcf3f"
	}
}