Developer Portal- Metodos De pago

Metodos De pago

VARIABLE RECURRENT PAYMENT

Un Variable Recurring Payment (VRP) es un tipo de pago recurrente definido en el estándar Open Banking que permite a un tercero autorizado (TPP) realizar pagos automáticos desde la cuenta del cliente, con montos variables, dentro de límites previamente acordados (por ejemplo, monto máximo por transacción, límites por período y fechas de vigencia). A diferencia de un débito directo tradicional:

El cliente da un solo consentimiento inicial. Los pagos son flexibles en importe y frecuencia, pero siempre respetando los límites definidos. Se usa para casos como sweeping (mover dinero entre cuentas propias), suscripciones o pagos dinámicos.

IMPORTANTE VARIABLES

Las variables de ejemplo no son las que podria utilizar, al momento de integrarse e iniciar el proceso BAM le compartira un archivo .json el cual contendra todas las variables que se utilizan en los siguientes metodos, tomarlo en cuenta durante el proceso de desarrollo y pruebas.

Estos son los métodos para poder realizar una prueba al caso de uso "Dispersión de Fondos".

Paso 1. Método GET Get OIDC well-known end-point

El “Get OIDC well-known end-point” es la petición HTTP GET que un cliente envía a la ruta /.well-known/openid-configuration de un servidor OpenID Connect para descargar, en formato JSON, la configuración pública del proveedor: URLs de autorización, token, revocación y claves (JWKS), scopes soportados, algoritmos de firma, etc.

Para poder ejecutar el siguiente método se debe de tomar en cuenta haber realizado correctamente las configuraciones necesarias.

GET {{issuer}}/.well-known/openid-configuration

Parameters

Name	Type	Location	Example Value
{{issuer}} Required	String	Domain	`https://auth1.sbx.bam.com.gt`
Content-Type Required	String	Header	`application/x-www-form-urlencoded`
Authorization Required	String	Header	`Basic {{basicToken}}`

Valor de Variables

Tomar en cuenta que los valores de {{issuer}}, {{basicToken}} y variables adicionales estaran en el archivo .json que le comparte BAM al momento de su integracion.

Responses

200 - Succesful

{
    "issuer": "https://auth1.sbx.bam.com.gt",
    "claims_parameter_supported": true,
    "claims_supported": [
        "openbanking_intent_id",
        "acr"
    ],
    "grant_types_supported": [
        "authorization_code",
        "client_credentials",
        "refresh_token",
        "urn:ietf:params:oauth:grant-type:jwt-bearer",
        "urn:openid:params:grant-type:ciba"
    ],
    "response_types_supported": [
        "code",
        "code id_token"
    ],
    "request_parameter_supported": true,
    "request_uri_parameter_supported": false,
    "require_request_uri_registration": true,
    "scopes_supported": [
        "openid",
        "accounts",
        "payments",
        "fundsconfirmations",
        "consents",
        "resources",
        "credit-cards-accounts",
        "customers",
        "loans",
        "financings",
        "invoice-financings",
        "unarranged-accounts-overdraft",
        "consumption",
        "lg",
        "recurring-payments",
        "bank-fixed-incomes",
        "recurring-consent"
    ],
    "token_endpoint_auth_methods_supported": [
        "client_secret_basic",
        "client_secret_jwt",
        "tls_client_auth",
        "private_key_jwt"
    ],
    "tls_client_certificate_bound_access_tokens": true,
    "code_challenge_methods_supported": [],
    "claim_types_supported": [
        "normal"
    ],
    "subject_types_supported": [
        "public"
    ],
    "token_endpoint": "https://as1.sbx.bam.com.gt/token",
    "authorization_endpoint": "https://auth1.sbx.bam.com.gt/auth",
    "registration_endpoint": "https://rs1.sbx.bam.com.gt/dynamic-client-registration/v3.2/register",
    "jwks_uri": "https://keystore.openbankingtest.org.uk/BAM/sbx.bam.com.gt.jwks",
    "userinfo_endpoint": "https://as1.sbx.bam.com.gt/userinfo",
    "introspection_endpoint": "https://as1.sbx.bam.com.gt/introspection",
    "revocation_endpoint": "https://as1.sbx.bam.com.gt/token/revoke",
    "pushed_authorization_request_endpoint": "https://as1.sbx.bam.com.gt/par",
    "backchannel_authentication_endpoint": "https://as1.sbx.bam.com.gt/bc-authorize",
    "backchannel_token_delivery_modes_supported": [
        "poll",
        "ping",
        "push"
    ],
    "backchannel_authentication_request_signing_alg_values_supported": [
        "none",
        "PS256",
        "RS256",
        "HS256"
    ],
    "backchannel_user_code_parameter_supported": false,
    "id_token_signing_alg_values_supported": [
        "none",
        "PS256",
        "RS256",
        "HS256"
    ],
    "request_object_signing_alg_values_supported": [
        "none",
        "PS256",
        "RS256",
        "HS256"
    ],
    "request_object_encryption_alg_values_supported": [
        "RSA-OAEP"
    ],
    "request_object_encryption_enc_values_supported": [
        "A256GCM"
    ],
    "token_endpoint_auth_signing_alg_values_supported": [
        "none",
        "PS256",
        "RS256",
        "HS256"
    ],
    "acr_values_supported": [],
    "mtls_endpoint_aliases": {
        "token_endpoint": "https://as1.sbx.bam.com.gt/token",
        "revocation_endpoint": "https://as1.sbx.bam.com.gt/token/revoke",
        "introspection_endpoint": "https://as1.sbx.bam.com.gt/introspection",
        "pushed_authorization_request_endpoint": "https://as1.sbx.bam.com.gt/par"
    },
    "authorization_details_types_supported": [],
    "authorization_signing_alg_values_supported": [],
    "authorization_encryption_alg_values_supported": [],
    "authorization_encryption_enc_values_supported": [],
    "response_modes_supported": [
        "query",
        "fragment"
    ],
    "userinfo_signing_alg_values_supported": [
        "PS256",
        "RS256",
        "HS256",
        "none"
    ],
    "userinfo_encryption_alg_values_supported": [],
    "userinfo_encryption_enc_values_supported": [],
    "id_token_encryption_alg_values_supported": [
        "RSA-OAEP-256"
    ],
    "id_token_encryption_enc_values_supported": [
        "A128CBC-HS256"
    ]
}

400 - Bad Request

{
GET https://auth1.sbx.bam.com.gl/.well-known/openid-configuration
Error: getaddrinfo ENOTFOUND auth1.sbx.bam.com.gl
Request Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Njc2ZWYyZjktYTllMS00ODY5LWFlZDEtNjJkOTRkNGE4ZTZjOmQyN2JlNDY4LWQxMWQtNDY3ZS04YTQwLTk3Y2Y5OGYzMDRmNA==
User-Agent: PostmanRuntime/7.44.0
Accept: */\*
Postman-Token: 87139bcf-2536-4908-934e-8587e2962203
Host: auth1.sbx.bam.com.gl
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
}

Paso 2. Método POST 1000: POST Client Credentials Grant (payments scope)

Este endpoint sirve para que la aplicación intercambie sus credenciales de cliente por un token de acceso limitado al ámbito de pagos, permitiéndole luego invocar las APIs de pago de forma segura y sin requerir la intervención de un usuario

Para poder ejecutar el siguiente método se debe de tomar en cuenta haber realizado correctamente las configuraciones anteriores.

POST `{{tokenEndpoint}}`

Parameters

Name	Type	Location	Example Value
{{tokenEndpoint}} Required	String	Domain	`https://as1.sbx.bam.com.gt/token`
Content-Type Required	String	Header	`application/x-www-form-urlencoded`
grand_type Required	String	Body	`client_credentials`
scope Required	String	Body	`payments openid`
AuthorizationRequired	String	Header	Basic `{{basicToken}}`

Valor de Variables

Tomar en cuenta el valor de {{tokenEndpoint}}, {{basicToken}} y el resto de variables estara en el archivo .json que le comparte BAM al momento de su integracion.

Responses

200 - Succesful

{
    "access_token": "f1005d18-60ac-4afd-ad33-876a485330e6",
    "token_type": "Bearer",
    "expires_in": 600,
    "scope": "payments"
}

400 - Bad Request

{
    "error": "invalid_client",
    "error_description": "authorization_header_incorrect: Authorization header must of the format 'Basic <token>'"
}

Paso 3. Método POST 2000: POST VRP Payment Consents

Este endpoint permite al usuario solicitar la creación de un consentimiento para pagos variables recurrentes. La solicitud incluye los metadatos necesarios para que la entidad bancaria evalúe la operación. Una vez validada, se genera un ConsentId único que será utilizado en los pasos posteriores del proceso de autorización y ejecución del pago.

Para poder ejecutar el siguiente método se debe de tomar en cuenta haber realizado correctamente las configuraciones anteriores.

POST `{{rs}}/open-banking/v3.1/pisp/domestic-vrp-consents`

Parameters

Name	Type	Location	Example Value
{{rs}} Required	String	Domain	`https://rs1.sbx.bam.com.gt`
Content-Type Required	String	Header	`application/json`
Authorization Required	String	Header	`Bearer {{token-from-client-credentials-grant-payments}}`
x-fapi-interaction-id Required	String	Header	`{{interactionId}}`
x-fapi-financial-id Required	String	Header	`{{obParticipantId}}`
x-fapi-customer-ip-address Required	String	Header	`10.1.1.10`

Valores de Variables

Tomar en cuenta que el valor de {{rs}}, {{interactionId}}, {{obParticipantId}} estara en el archivo .json que le comparte BAM al momento de su integracion.
Valor de {{token-from-client-credentials-grant-payments}} este es el valor de access_token que devuelve en el paso POST 1000: POST Client Credentials Grant (payments scope)

IMPORTANTE

En este request se debe de tomar en cuenta añadir una breve descripcion de la transaccion, esta se podra añadir dentro de "RemittanceInformation" en el campo "Unstructured" de la siguiente manera: "VRP - CUOTAS - NombreTPP"

Request Body

{
    "Data": {
        "ControlParameters": {
            "PSUAuthenticationMethods": [
                "UK.OBIE.SCA"
            ],
            "VRPType": [
                "UK.OBIE.VRPType.Sweeping"
            ],
            "ValidFromDateTime": "2025-04-01T00:00:00+00:00",
            "ValidToDateTime": "2025-12-31T00:00:00+00:00",
            "MaximumIndividualAmount": {
                "Amount": "1000",
                "Currency": "GTQ"
            },
            "PeriodicLimits": [
                {
                    "Amount": "10000",
                    "Currency": "GTQ",
                    "PeriodAlignment": "Consent",
                    "PeriodType": "Week"
                }
            ]
        },
        "Initiation": {
            "CreditorAccount": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "01000160000001",
                "Name": "Wilfred Cunningham"
            }
        },
        "RemittanceInformation": {
            "Reference": "{{randomTransactionType}}",
            "Unstructured": "VRP - Nombre del cliente"
        }
    },
    "Risk": {}
}

Detalles de Request Body

Descripción de los campos principales del payload VRP

`Data`

Contiene toda la información funcional del consentimiento VRP:

Parámetros de control (límites y reglas).
Datos de iniciación (beneficiario).
Información de remesa (referencias).

`Data.ControlParameters`

Define las reglas y límites del consentimiento:

PSUAuthenticationMethods
Métodos de autenticación permitidos para el usuario (PSU).
- UK.OBIE.SCA = Strong Customer Authentication.
VRPType
Tipo de VRP.
- UK.OBIE.VRPType.Sweeping = movimiento automatizado entre cuentas propias.
ValidFromDateTime / ValidToDateTime
Rango de vigencia del consentimiento (formato ISO 8601).
MaximumIndividualAmount
Límite por transacción individual:
- Amount: monto máximo.
- Currency: moneda (ISO 4217).
PeriodicLimits
Límite acumulado por período:
- Amount / Currency: tope total.
- PeriodType: tipo de período (Day, Week, Month).
- PeriodAlignment:
  - Consent = desde la creación del consentimiento.
  - Calendar = alineado al calendario natural.

`Data.Initiation`

Datos del beneficiario (acreedor):

CreditorAccount
- SchemeName: esquema de cuenta (UK.OBIE.SortCodeAccountNumber).
- Identification: identificador (sort code + account number).
- Name: nombre del beneficiario.

`Data.RemittanceInformation`

Información para conciliación:

Reference: referencia breve y estructurada (p. ej., número de factura).
Unstructured: texto libre adicional (comentario).

Responses

201 - Consents Created

{
    "Data": {
        "ControlParameters": {
            "PSUAuthenticationMethods": [
                "UK.OBIE.SCA"
            ],
            "VRPType": [
                "UK.OBIE.VRPType.Sweeping"
            ],
            "ValidFromDateTime": "2025-04-01T00:00:00+00:00",
            "ValidToDateTime": "2025-12-31T00:00:00+00:00",
            "MaximumIndividualAmount": {
                "Amount": "1000",
                "Currency": "GTQ"
            },
            "PeriodicLimits": [
                {
                    "Amount": "10000",
                    "Currency": "GTQ",
                    "PeriodAlignment": "Consent",
                    "PeriodType": "Week"
                }
            ]
        },
        "Initiation": {
            "CreditorAccount": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "01000160000001",
                "Name": "Wilfred Cunningham"
            }
        },
        "RemittanceInformation": {
            "Reference": "payment",
            "Unstructured": "VRP - Nombre del cliente"
        },
        "ConsentId": "vrp-840ace87-fdbf-4509-84e2-f110b1bfe7eb",
        "Status": "AwaitingAuthorisation",
        "CreationDateTime": "2025-09-16T23:10:24.670Z",
        "StatusUpdateDateTime": "2025-09-16T23:10:24.670Z"
    },
    "Risk": {},
    "Links": {
        "Self": "https://rs1.sbx.bam.com.gt/open-banking/v3.1/pisp/domestic-vrp-consents/vrp-840ace87-fdbf-4509-84e2-f110b1bfe7eb"
    },
    "Meta": {}
}

400 - Bad Request

{
    "Code": "UK.OBIE.Resource.InvalidFormat",
    "Message": "invalid_message_format: json payload does not match schema undefined",
    "Errors": [
        {
            "ErrorCode": "UK.OBIE.Resource.InvalidFormat",
            "Message": "invalid_message_format: json payload does not match schema undefined"
        }
    ]
}

Paso 4. Método GET Prepare private key JWT

Este método construye un JSON Web Token que incluye los datos de identificación del cliente (issuer, subject, etc) y lo firma con la clave privada, de modo que al enviarlo como prueba (client_assertion) el servidor de autorización pueda validar de forma segura la identidad del cliente sin usar secretos compartidos.

Para poder ejecutar el siguiente método se debe de tomar en cuenta haber realizado correctamente las configuraciones anteriores.

GET `{{rs}}/o3/v1.0/message-signature`

Parameters

Name	Type	Location	Example Value
{{rs}} Required	String	Domain	`https://rs1.sbx.bam.com.gt`
Content-Type Required	String	Header	`application/json`

Example Request Body

{
    "header": {
        "alg": "PS256",
        "kid": "{{kid-local}}"
    },
    "body": {
        "aud": "{{issuer}}",
        "exp": {{exp}},
        "iss": "{{_clientId}}",
        "sub": "{{_clientId}}",
        "jti": "{{$guid}}",
        "iat": {{nbf}}
    },
    "signingKeyPEM": "{{pem-local}}"
}

Valores de Variables

Tomar en cuenta que los valores de {{rs}}, {{kid-local}}, {{issuer}}, {{_clientId}}, {{$guid}}, {{kid-local}}, {{pem-local}} y variables adicionales estaran en el archivo .json que le comparte BAM al momento de su integracion.
Tomar en cuenta que las variables de {{exp}} y {{nbf}} se utilizan para determinar la valides y duración del token, ejemplo en postman en Pre-request.

Responses

200 - Succesful

eyJhbGciOiJQUzI1NiIsImtpZCI6ImZja2ZYQmRmdllSZmR5YTVTdDhsVklPa1AyYyJ9.eyJhdWQiOiJodHRwczovL2F1dGgxLnNieC5iYW0uY29tLmd0IiwiZXhwIjoxNzUwMzY1MDY5LjUyNiwiaXNzIjoiNjc2ZWYyZjktYTllMS00ODY5LWFlZDEtNjJkOTRkNGE4ZTZjIiwic3ViIjoiNjc2ZWYyZjktYTllMS00ODY5LWFlZDEtNjJkOTRkNGE4ZTZjIiwianRpIjoiNGU2MGJkZTQtNzc1MC00NDQwLWJkZjYtYjU1OGIwNjM3ZTVjIiwiaWF0IjoxNzUwMzY0NzU5LjUyNn0.vwivopt3u9Wkn8oXjU6nj8jX_6UunBjKvM05YuCs-DGvBhcmsc7VqetS2p3ll8RZrjGvGYc7pXabXn79VLwmWAsAWCzGYoD9WfZaA0osrnSo5BhffdiLncTsJuq0tCfMsMCY9q7pumHLAtvWly9oi7osdPPozE37DBtH64PAr1Mdjw7cj1WcZAkt5rOt0niKnk28XxulEpUjBqtKhqilcdYCUQwAVkW0N7rpuS5WpRMD-BXKFzeC1llCHi4Lx4P87_M6Yma4SGSRnLCPHhYstJGvhNlCEswaeNNMX4cBgnsKsrDAnFGyY_-ST-EQWHfc8DIPNpCIoVaTxAKJ38UJQQ

400 - Bad Request

payload is empty

Paso 5. Método POST POST to PAR end-point

Este endpoint recibe por POST todos los parámetros de la petición de autorización, los almacena de forma segura y devuelve un identificador (request_uri). Más tarde, ese request_uri se incluye en la URL de autorización que se le muestra al usuario. Así se asegura que los datos no viajen expuestos en la barra del navegador, se validan antes de redirigir al usuario y se evitan problemas de URLs demasiado largas o manipuladas.

Para poder ejecutar el siguiente método se debe de tomar en cuenta haber realizado correctamente las configuraciones anteriores.

POST `{{par-endpoint}}`

Parameters

Name	Type	Location	Value
{{par-endpoint}} Required	String	Domain	`https://as1.sbx.bam.com.gt/par`
Content-Type Required	String	Header	`application/x-www-form-urlencoded`
Authorization Required	String	Header	`Basic {{basicToken}}`

Valores de Variables

Variable {{par-endpoint}} es el valor pushed_authorization_request_endpoint que devuelve el método GET Get OIDC well-known end-point.
Tomar en cuenta que el valor de {{basicToken}} y variables adicionales estaran en el archivo .json que le comparte BAM al momento de su integracion.

Request Body

El cuerpo de la solicitud de este método en postman esta en el formato "x-www-form-urlencoded".

Parameters

Name	Type	Location	Value
client_id Required	String	body	`{{_clientId}}`
redirect_uri Required	String	body	`{{redirectUrl}}`
scope Required	String	body	`payments:{{intent-id}} openid`
response_type Required	String	body	`code`
state Required	String	body	`{{$guid}}`
code_challenge Required	String	body	`{{code-challenge}}`
client_assertion_type Required	String	body	`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
client_assertion Required	String	body	`{{private_key_jwt}}`
code_challenge_method Required	String	body	`S256`

Valores de Variables en Body

Tomar en cuenta que los valores de {{_clientId}}, {{redirect_uri}} y variables adicionales estaran en el archivo .json que le comparte BAM al momento de su integracion.
Valor {{$guid}} es un identificador unico generado aleatoriamente en el momento de la dejecución de la solicitud.
Valor de {{intent-id}} es igual a el valor de intent-id que devuelve POST 2000: POST domestic-payment-consents.
Valor de {{code-challenge}} es igual a el valor codeChallenge que devuelve GET Prepare private key JWT.
Valor de {{private_key_jwt}} es igual a el valor responseBody que devuelve GET Prepare private key JWT.

Responses

200 - Succesful

{
    "request_uri": "urn:ietf:params:oauth:request_uri:a5c5bf28-fbe3-4533-b1db-b654957ba0c3",
    "expires_in": 300
}

400 - Bad Request

{
    "error": "invalid_client",
    "error_description": "private_key_jwt_sig_check: client secret jwt has an invalid signature - verify_error - Invalid URL"
}

Paso 6. Método GET O3 Util: GET par-auth-code-url

Este endpoint genera y devuelve la URL a la que debes redirigir al usuario para que autorice la petición de permisos. En lugar de exponer todos los parámetros en la barra de direcciones, aquí se incluye un identificador seguro que apunta a la solicitud ya registrada y validada en el servidor. De ese modo se ocultan los detalles sensibles, se evitan manipulaciones y se agiliza el flujo de autorización.

Para poder ejecutar el siguiente método se debe de tomar en cuenta haber realizado correctamente las configuraciones anteriores.

GET {{rs}}/o3/v1.0/par-auth-code-url/{{intent-id}}?request_uri={{par-urn}}&response_type=code&scope={{request-scope}}

Parameters

Name	Type	Location	Value
{{rs}} Required	String	Domain	`https://rs1.sbx.bam.com.gt`
{{intent-id}} Required	String	Path Parameter	`pay-fi-d468bf6f-5413-4be7-90da-f4f9502afe87`
{{par-urn}} Required	String	Query Parameter	`urn:ietf:params:oauth:request_uri:ae217cda-eaa2-45d1-ad1e-76f3d5e67f65`
{{request-scope}} Required	String	Query Parameter	`{{request-scope}}`

Valores de Variables de Query Params

valor de {{rs}} estara en el archivo .json que le comparte BAM al momento de su integracion.
Valor de {{intent-id}} es igual a el valor de ConsentId que se devuelve en POST 2000: 2000: POST domestic-payment-consents.
Valor de {{par-urn}} es igual a el valor de request_uri que se devulve en POST POST to PAR end-point.
Valor de {{request-scope}} Se le da el valor de payments en el método POST 2000: POST domestic-payment-consents.

Header Params

Name	Type	Location	Value
Authorization Required	String	Header	`Basic {{basicToken}}`

Valores de Variables de Query Params

Valor de {{basicToken}} estara en el archivo .json que le comparte BAM al momento de su integracion.

Responses

200 - Succesful

html
https://auth1.sbx.bam.com.gt/auth?client_id=676ef2f9-a9e1-4869-aed1-62d94d4a8e6c&response_type=code&scope=payments&request_uri=urn:ietf:params:oauth:request_uri:4ef85326-10a5-4ad1-950f-756d2c891272

400 - Bad Request

{
    "error": "general_error",
    "error_description": "default: An error occoured with an indeterminate error code request_uri_not_specified"
}

Paso 7. IMPORTANTE Requerimiento de API

Al finalizar el proceso anterior este es un punto importante a mencionar, el enpoint anterior devuelve una URL de redirección que contiene datos que son esenciales para continuar con el procedimiento, el cual se debe de seguir de el lado de su organización, por lo tanto.

Se le solicita la implementación de una API, con el fin de que reciba la url de redirección y que responde el endpoint de BAM, por lo tanto su equipo debe de implementar una API publica la cual debe de estar a la espera de que nuestro endpoint le envié la URL de redirección.

Ejemplo de url de redirección enviado por el enpoint de BAM:

https://auth1.sbx.bam.com.gt/auth?client_id=676ef2f9-a9e1-4869-aed1-62d94d4a8e6c&response_type=code&scope=payments&request_uri=urn:ietf:params:oauth:request_uri:4ef85326-10a5-4ad1-950f-756d2c891272

Al momento de recibir La URL de redirección idealmente la api de su organización api debería de responder con un 200 - Succesful indicando que recibió correctamente la url.

Responses

200 - Succesful

{
    "status": "success",
    "message": "URL de redireccion recibida"
}

Paso 8. Método POST 5003: POST Auth Code Grant (payments scope)

Para poder ejecutar el siguiente método se debe de tomar en cuenta haber realizado correctamente las configuraciones anteriores, tomar en cuenta que acá es donde se espera la respuesta de la api que implementara su organización, deberá de retornar el consentId para continuar con el flujo en los endpoint de BAM.

POST `{{tokenEndpoint}}`

Parameters

Name	Type	Location	Value
{{tokenEndpoint}} Required	String	Domain	`https://as1.sbx.bam.com.gt/token`
Content-Type Required	String	Header	`application/x-www-form-urlencoded`
Authorization Required	String	Header	`Basic {{basicToken}}`
grand_type Required	String	Body	`authorization_code`
scope Required	String	Body	`payments`
code Required	String	Body	`{{authorizationCode}}`
redirect_uri Required	String	Body	`{{redirectUrl}}`
code_verifier Required	String	Body	`{{code-verifier}}`

Valores de Variables

Valor de {{redirect_uri}}, {{authorizationCode}} y Basic {{basicToken}} estara en el archivo .json que le comparte BAM al momento de su integracion.
Valor de code Se igual a el valor que retornara la api de su organización para continuar con el flujo.
Valor de {{code-verifier}} es igual a el valor de codeVerifier que devuelve el metodo GET Prepare private key JWT

Responses

200 - Succesful

{
    "access_token": "29a663a5-ba6c-4f81-a7db-bd379690df43",
    "expires_in": 432000,
    "token_type": "Bearer",
    "scope": "payments:pay-di-8e20f314-141e-49c5-80c0-7b6e9a1ca6a2 openid",
    "state": "640737a3-da04-40f0-badc-47b4315e52bd",
    "refresh_token": "920595c7-4d8d-484e-96a2-6c37f5b831b2"
}

Para poder tener una trazabilidad correcta al recibir una respuesta exitosa en el response se encontrara la variable "scope" la cual incluye el consentId al que pertenece el codigo de autorizacion.

400 - Bad Request

{
    "error": "invalid_grant",
    "error_description": "invalid_auth_code_request_uri"
}

Paso 9. Método POST 6000: POST domestic-vrps

Una vez que el usuario autoriza el consentimiento de pago con el archivo, el proveedor envía de inmediato una petición para iniciar el procesamiento de esa operación. Esta solicitud funciona como la instrucción oficial al banco para que comience a tramitar el pago usando el mismo archivo autorizado, aunque en momentos de alta demanda el banco puede tardar en ponerla en marcha. Es crucial que todos los datos de la nueva instrucción de pago coincidan exactamente con los incluidos en el consentimiento previamente aprobado; si existe alguna diferencia, el banco rechazará la petición con un error de formato. Cuando la solicitud se acepta sin problemas, el sistema asigna un estado al pago, que puede indicar que está pendiente de inicio, que la iniciación ha fallado o que el pago se ha completado con éxito.

Para poder ejecutar el siguiente método se debe de tomar en cuenta haber realizado correctamente las configuraciones anteriores.

POST `{{rs}}/open-banking/v3.1/pisp/domestic-vrps`

Parameters

Name	Type	Location	Value
{{rs}} Required	String	Domain	`https://rs1.sbx.bam.com.gt`
Content-Type Required	String	Header	`application/json`
x-fapi-financial-id Required	String	Header	`{{obParticipantId}}`
x-fapi-customer-ip-address Required	String	Header	`10.1.1.10`
x-fapi-interaction-id Required	String	Header	`{{interactionId}}`
Authorization Required	String	Header	`Bearer {{token-from-auth-code-grant-payments}}`

Valores de Variables

Valor de {{token-from-client-credentials-grant-payments}} este es el valor de access_token que devuelve en el paso POST 5003: POST Auth Code Grant (payments scope)
Valor de {{obParticipantId}}, {{interactionId}} estara en el archivo .json que le comparte BAM al momento de su integracion.
Tomar en cuenta que el valor de {{interactionId}} estara en el archivo .json que le comparte BAM al momento de su integracion.
Valor de {{interactionId}} es un UUID de interacción que cambia con cada ejecucion.

Request Body

{
    "Data": {
        "ConsentId": "{{payment-consent-id}}",
        "Initiation": {{Initiation}},
        "PSUAuthenticationMethod": "UK.OBIE.SCA",
        "VRPType": "UK.OBIE.VRPType.Sweeping",
        "Instruction": {
            "InstructionIdentification": "identification",
            "EndToEndIdentification": "e2eid",
            "CreditorAccount": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "01000160000001",
                "Name": "Wilfred Cunningham"
            },
            "InstructedAmount": {
                "Currency": "GTQ",
                "Amount": "300"
            },
            "RemittanceInformation": {
                "Unstructured": "COMPRA BAM VRP"
            }
        }
    },
    "Risk": {}
}}

Valores de Variables en Body

Valor de {{payment-consent-id}} es igual a el valor de ConsentId que se devuelve en POST 2000: POST domestic-payment-consents,
Valor de {{Initiation}} es igual a el valor de {{Initiation}} que se devuelve en el metodo POST 2000: POST domestic-payment-consents.

Responses

201 - Consents Created

{
    "Data": {
        "DomesticVRPId": "obvrp-0644768db25c4fbfb47770977e55ee6f",
        "ConsentId": "vrp-8301615d-fd7a-40b1-86a1-dd5edc0c98de",
        "Status": "Pending",
        "CreationDateTime": "2025-09-16T22:51:18.047Z",
        "StatusUpdateDateTime": "2025-09-16T22:51:18.047Z",
        "Charges": [
            {
                "ChargeBearer": "BorneByCreditor",
                "Type": "UK.OBIE.CHAPSOut",
                "Amount": {
                    "Amount": "12651436834",
                    "Currency": "VOB"
                }
            }
        ],
        "Initiation": {
            "CreditorAccount": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "01000160000001",
                "Name": "Wilfred Cunningham"
            }
        },
        "Instruction": {
            "InstructedAmount": {
                "Currency": "GTQ",
                "Amount": "300"
            },
            "EndToEndIdentification": "e2eid",
            "CreditorAccount": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "01000160000001",
                "Name": "Wilfred Cunningham"
            },
            "InstructionIdentification": "identification"
        }
    },
    "Risk": {},
    "Links": {
        "Self": "https://rs1.sbx.bam.com.gt/open-banking/v3.1/pisp/domestic-vrps/obvrp-0644768db25c4fbfb47770977e55ee6f"
    },
    "Meta": {}
}

401 - Unauthorized

{
    "Code": "UK.OBIE.Header.Invalid",
    "Message": "no_access_token: invalid access token",
    "Errors": [
        {
            "ErrorCode": "UK.OBIE.Header.Invalid",
            "Message": "no_access_token: invalid access token",
            "Path": "Authorization"
        }
    ]
}

Paso 10. Método GET 6001: GET domestic-vrps-consents

El proveedor de servicios puede recuperar en cualquier momento el recurso de pago basado en archivo para conocer su estado. La respuesta siempre incluirá uno de estos tres códigos: InitiationPending, cuando está pendiente de iniciación; InitiationFailed, si la fase inicial ha fallado; o InitiationCompleted, cuando la iniciación se ha completado con éxito.

Para poder ejecutar el siguiente método se debe de tomar en cuenta haber realizado correctamente las configuraciones anteriores.

GET `6001: GET domestic-vrps-consents`

Parameters

Name	Type	Location	Value
{{rs}} Required	String	Domain	`https://rs1.sbx.bam.com.gt`
{{payment-id}} Required	String	Path Parameter	`fp-5b3c790b595e43618e00eeeb2799c658`
Content-Type Required	String	Header	`application/json`
x-fapi-interaction-id Required	String	Header	`{{interactionId}}`
Authorization Required	String	Header	`Bearer {{token-from-client-credentials-grant-payments}}`
x-fapi-financial-id Required	String	Header	`{{obParticipantId}}`
x-fapi-customer-ip-address Required	String	Header	`10.1.1.10`

Valores de Variables

Valor de {{payment-id}} es igual a el valor DomesticPaymentId que devuelve POST 6000: POST domestic-payments
Tomar en cuenta que el valor de {{interactionId}} estara en el archivo .json que le comparte BAM al momento de su integracion.
Valor de {{interactionId}} es un UUID de interacción que cambia con cada ejecucion.
Valor de {{token-from-client-credentials-grant-payments}} este es el valor de access_token que devuelve en el paso POST 1000: POST Client Credentials Grant (payments scope)

Responses

200 - Succesful

{
    "Data": {
        "ControlParameters": {
            "PSUAuthenticationMethods": [
                "UK.OBIE.SCA"
            ],
            "VRPType": [
                "UK.OBIE.VRPType.Sweeping"
            ],
            "ValidFromDateTime": "2025-04-01T00:00:00+00:00",
            "ValidToDateTime": "2025-12-31T00:00:00+00:00",
            "MaximumIndividualAmount": {
                "Amount": "1000",
                "Currency": "GTQ"
            },
            "PeriodicLimits": [
                {
                    "Amount": "10000",
                    "Currency": "GTQ",
                    "PeriodAlignment": "Consent",
                    "PeriodType": "Week"
                }
            ]
        },
        "Initiation": {
            "CreditorAccount": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "01000160000001",
                "Name": "Wilfred Cunningham"
            }
        },
        "ConsentId": "vrp-8301615d-fd7a-40b1-86a1-dd5edc0c98de",
        "Status": "Authorised",
        "CreationDateTime": "2025-09-16T22:50:25.620Z",
        "StatusUpdateDateTime": "2025-09-16T22:51:02.030Z"
    },
    "Risk": {},
    "Links": {
        "Self": "https://rs1.sbx.bam.com.gt/open-banking/v3.1/pisp/domestic-vrp-consents/vrp-8301615d-fd7a-40b1-86a1-dd5edc0c98de"
    },
    "Meta": {}
}

403 - Forbidden

{
    "Code": "UK.OBIE.Header.Invalid",
    "Message": "token_expired: Token has expired",
    "Errors": [
        {
            "ErrorCode": "UK.OBIE.Header.Invalid",
            "Message": "token_expired: Token has expired",
            "Path": "Authorization"
        }
    ]
}

Table of Content

Please wait

Developer Portal

Metodos De pago

IMPORTANTE VARIABLES

Paso 1. Método GET Get OIDC well-known end-point

GET {{issuer}}/.well-known/openid-configuration

Parameters

Valor de Variables

Responses

200 - Succesful

400 - Bad Request

Paso 2. Método POST 1000: POST Client Credentials Grant (payments scope)

POST {{tokenEndpoint}}

Parameters

Valor de Variables

Responses

200 - Succesful

400 - Bad Request

Paso 3. Método POST 2000: POST VRP Payment Consents

POST {{rs}}/open-banking/v3.1/pisp/domestic-vrp-consents

Parameters

Valores de Variables

IMPORTANTE

Request Body

Detalles de Request Body

Descripción de los campos principales del payload VRP

Data

Data.ControlParameters

Data.Initiation

Data.RemittanceInformation

Responses

201 - Consents Created

400 - Bad Request

Paso 4. Método GET Prepare private key JWT

GET {{rs}}/o3/v1.0/message-signature

Parameters

Example Request Body

Valores de Variables

Responses

200 - Succesful

400 - Bad Request

Paso 5. Método POST POST to PAR end-point

POST {{par-endpoint}}

Parameters

Valores de Variables

Request Body

Parameters

Valores de Variables en Body

Responses

200 - Succesful

400 - Bad Request

Paso 6. Método GET O3 Util: GET par-auth-code-url

GET {{rs}}/o3/v1.0/par-auth-code-url/{{intent-id}}?request_uri={{par-urn}}&response_type=code&scope={{request-scope}}

Parameters

Valores de Variables de Query Params

Header Params

Valores de Variables de Query Params

Responses

200 - Succesful

400 - Bad Request

Paso 7. IMPORTANTE Requerimiento de API

Responses

200 - Succesful

Paso 8. Método POST 5003: POST Auth Code Grant (payments scope)

POST {{tokenEndpoint}}

Parameters

Valores de Variables

Responses

200 - Succesful

400 - Bad Request

Paso 9. Método POST 6000: POST domestic-vrps

POST {{rs}}/open-banking/v3.1/pisp/domestic-vrps

Parameters

Valores de Variables

Request Body

Valores de Variables en Body

Responses

201 - Consents Created

401 - Unauthorized

Paso 10. Método GET 6001: GET domestic-vrps-consents

GET 6001: GET domestic-vrps-consents

POST `{{tokenEndpoint}}`

POST `{{rs}}/open-banking/v3.1/pisp/domestic-vrp-consents`

`Data`

`Data.ControlParameters`

`Data.Initiation`

`Data.RemittanceInformation`

GET `{{rs}}/o3/v1.0/message-signature`

POST `{{par-endpoint}}`

POST `{{tokenEndpoint}}`

POST `{{rs}}/open-banking/v3.1/pisp/domestic-vrps`

GET `6001: GET domestic-vrps-consents`