Pagfor

El proceso de PagFor a través de la API de BTG Pactual Empresas ofrece la capacidad de automatizar el pago a sus proveedores y permitirles anticipar estos cobros, a diferencia de los métodos de pago habituales ofrecidos por la API.

Al utilizar el Pagfor, el proceso de pago se mantiene igual:

• La API de pagos se utiliza para crear una iniciación de pago;
• En el internet banking o en la aplicación, uno o más usuarios (respetando firmas y poderes) aprueban el pago.

A partir de este punto, el pago se convierte en un cobro por recibir para el receptor del pago (en este caso, un proveedor) y estará disponible para anticipación en el panel de anticipación de proveedores.

Utilización

La modalidad de PagFor está disponible únicamente para los siguientes tipos de pago:

Tipo
BANKSLIP
PIX_MANUAL
TED
TEF

Para realizar un pago PagFor, es necesario ajustar el payload para cumplir con algunos requisitos:

1- Es necesario incluir, en la raíz del objeto de pago, el agreementId previamente acordado entre el integrador y BTG Pactual Empresas.

1- Es necesario que el payload del pago contenga las instrucciones de PagFor dentro del objeto detail de la siguiente manera:

...

"detail": {
    ...

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

    ...
}

...

Máquina de estados

Si el cobro por recibir es anticipado por el proveedor, se generará una posición de crédito vinculada al pago que será liquidada en el paymentDate informado en el payload. En este escenario, el pago entrará en la siguiente máquina de estados:

Donde:

Status	Descripción
STARTED	Pago en espera de aprobación
SCHEDULED	Pago programado
CANCELED	Pago cancelado
FAILED	Error en el pago
RETAINED	Pago retenido por pendiente de autenticación por fraude
ANTICIPATION_STARTED	Orden de anticipación iniciada
ANTICIPATED	Orden de anticipación confirmada
ANTICIPATION_CONFIRMED	Posición de crédito de la anticipación liquidada

Si el cobro por recibir no es anticipado por el proveedor, el pago seguirá el flujo de un pago común.

Eventos de webhook

A continuación se listan los eventos específicos del Pagfor. Los demás eventos pueden consultarse en Pagos

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"
	}
}