Developer Portal- Metodos De pago

Metodos De pago

SINGLE DOMESTIC PAYMENT

El concepto de Single Domestic Payment en el marco de Open Banking se refiere a una transacción única de pago realizada dentro de una misma jurisdicción nacional, esta modalidad permite a los usuarios iniciar pagos directamente desde sus cuentas bancarias, sin necesidad de intermediarios tradicionales, como redes de tarjetas o procesadores externos.

A través de la infraestructura de Open Banking, los pagos domésticos únicos se ejecutan de forma segura, eficiente y transparente, cumpliendo con los principios de consentimiento explícito, autenticación fuerte del cliente (SCA) y trazabilidad regulatoria.

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.

Response

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.

Response

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 domestic-payment-consents

Este endpoint permite al usuario solicitar la creación de un consentimiento para pagos domésticos sin necesidad de proporcionar inicialmente los datos de cuenta ni identificar al titular. 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-payment-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 Variables

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: "PIS - CONTADO - NombreTPP"

Tambien se debe de considerar que este metodo tiene dos formas de ejecutarsem ya sea con un pago de contado o un pago a cuotas.

Para definir que tipo de pago se debera modificar el payload en este metodo.

El campo que se debe de agregar es "SupplementaryData": { "Installments": 12 } donde el valor de "Installments" define la cantidad de cuotas que se desean, si se desea un pago de contado este campo no se debe de agregar.

Request Body Para Pago de Contado

{
    "Data": {
        "ReadRefundAccount": "Yes",
        "Initiation": {
            "InstructionIdentification": "{{randomString-1}}",
            "EndToEndIdentification": "{{randomString-2}}",
            "InstructedAmount": {
                "Amount": "{{randomPrice}}",
                "Currency": "GTQ"
            },
            "CreditorAccount": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "000000{{randomBankAccount}}", // Numero de cuenta del beneficiario del pago (TPP)
                "Name": "{{randomCompanyName}}" // Nombre de la empresa beneficiaria del pago (TPP)
            },
            "DebtorAccount": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "08405109010102", // Numero de DPI del cliente a realizar la compra con un 0 a la izquierda agregado.
                "Name": "John Doe" // Nombre de la persona que realiza la compra
            },
            "RemittanceInformation": {
                "Reference": "{{randomTransactionType}}",
                "Unstructured": "PIS - CONTADO - NombreTPP"
            }
        }
    },
    "Risk": {}
}

Request Body Para Pago A Cuotas

{
    "Data": {
        "ReadRefundAccount": "Yes",
        "Initiation": {
            "InstructionIdentification": "{{randomString-1}}",
            "EndToEndIdentification": "{{randomString-2}}",
            "InstructedAmount": {
                "Amount": "{{randomPrice}}",
                "Currency": "GTQ"
            },
            "CreditorAccount": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "000000{{randomBankAccount}}", // Numero de cuenta del beneficiario del pago (TPP)
                "Name": "{{randomCompanyName}}" // Nombre de la empresa beneficiaria del pago (TPP)
            },
            "DebtorAccount": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "08405109010102", // Numero de DPI del cliente a realizar la compra con un 0 a la izquierda agregado
                "Name": "John Doe" // Nombre de la persona que realiza la compra
            },
            "RemittanceInformation": {
                "Reference": "{{randomTransactionType}}",
                "Unstructured": "PIS - CUOTAS - NombreTPP"
            },
            "SupplementaryData": {
                "Installments": 12
            }
        }
    },
    "Risk": {}
}

Detalles de Request Body

Data contiene la información principal del consentimiento de pago.
ReadRefundAccount: "Yes" indica que el usuario autoriza a la entidad bancaria a proporcionar los datos de la cuenta de reembolso en caso de que el pago sea revertido.
Data dentron de Initiation define los detalles de la transacción que se desea iniciar.
- Variables InstructionIdentification y EndToEndIdentification son identificadores únicos generados por el cliente (TPP) para rastrear la instrucción de pago. Se usan para trazabilidad y conciliación.
- Variable InstructedAmount Especifica el monto del pago:
  - Amount: valor del pago .
  - Currency: moneda utilizada, en este caso GTQ
- CreditorAccount Información de la cuenta que recibirá el pago:
  - SchemeName: esquema de identificación de cuenta.
  - Identification: número de cuenta del beneficiario(debe ser un numero de 14 digitos, si la cuenta tiene menos digitos, agregar "0" a la izquierda hasta completar 14 digitos). (EJ. Cuenta: 20360961 -> Identification: 00000020360961).
  - Name: nombre del beneficiario (empresa).
- DebtorAccount información de la cuenta que realiza el pago:
  - SchemeName: mismo esquema de identificación.
  - Identification: Numero de DPI del cliente a realizar la compra, y debe ser un numero de 14 digitos, por lo cual se debe de agregar un 0 a la izquierda del DPI.(EJ. DPI: 8664134430101 -> Identification: 08664134430101).
  - Name: nombre del titular de la cuenta.
- RemittanceInformationInformación adicional para el beneficiario:
  - Reference: tipo de transacción.
  - Unstructured: descripción libre del pago, por ejemplo: "PIS - CONTADO - NombreTPP".
- SupplementaryDataInformación adicional para definir pagos a cuotas:
  - Installments: número de cuotas.

Responses

201 - Consents Created

{
    "Data": {
        "ReadRefundAccount": "Yes",
        "Initiation": {
            "InstructionIdentification": "cXCN_DsVwOkaHhV",
            "EndToEndIdentification": "8SZU1iWT3xJNHd6",
            "InstructedAmount": {
                "Amount": "187.50",
                "Currency": "GTQ"
            },
            "CreditorAccount": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "00000020360961",
                "Name": "Hodkiewicz Group"
            },
            "DebtorAccount": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "10000109010102",
                "Name": "John Doe"
            },
            "RemittanceInformation": {
                "Reference": "withdrawal",
                "Unstructured": "2490 quibusdam et omnis"
            }
        },
        "ConsentId": "pay-di-8e20f314-141e-49c5-80c0-7b6e9a1ca6a2",
        "Status": "AwaitingAuthorisation",
        "CreationDateTime": "2025-08-29T18:21:04.436Z",
        "StatusUpdateDateTime": "2025-08-29T18:21:04.436Z"
    },
    "Risk": {},
    "Links": {
        "Self": "https://rs1.sbx.bam.com.gt/open-banking/v3.1/pisp/domestic-payment-consents/pay-di-8e20f314-141e-49c5-80c0-7b6e9a1ca6a2"
    },
    "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 Header Params

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

Responses

200 - Succesful


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

Response

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-payments

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-payments`

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

Valores de Variables 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.

{
    "InstructionIdentification": "cXCN_DsVwOkaHhV",
    "EndToEndIdentification": "8SZU1iWT3xJNHd6",
    "InstructedAmount": {
        "Amount": "187.50",
        "Currency": "GTQ"
    },
    "CreditorAccount": {
        "SchemeName": "UK.OBIE.SortCodeAccountNumber",
        "Identification": "00000020360961",
        "Name": "Hodkiewicz Group"
    },
    "DebtorAccount": {
        "SchemeName": "UK.OBIE.SortCodeAccountNumber",
        "Identification": "10000109010102",
        "Name": "John Doe"
    },
    "RemittanceInformation": {
        "Reference": "withdrawal",
        "Unstructured": "2490 quibusdam et omnis"
    }
}

Response

201 - Consents Created

{
    "Data": {
        "ConsentId": "pay-di-8e20f314-141e-49c5-80c0-7b6e9a1ca6a2",
        "Status": "Pending",
        "CreationDateTime": "2025-08-29T18:25:42.737Z",
        "StatusUpdateDateTime": "2025-08-29T18:25:42.737Z",
        "MultiAuthorisation": {
            "Status": "AwaitingFurtherAuthorisation"
        },
        "Charges": [
            {
                "ChargeBearer": "BorneByCreditor",
                "Type": "UK.OBIE.CHAPSOut",
                "Amount": {
                    "Amount": "12651436834",
                    "Currency": "VOB"
                }
            }
        ],
        "Initiation": {
            "InstructionIdentification": "cXCN_DsVwOkaHhV",
            "EndToEndIdentification": "8SZU1iWT3xJNHd6",
            "InstructedAmount": {
                "Amount": "187.50",
                "Currency": "GTQ"
            },
            "CreditorAccount": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "00000020360961",
                "Name": "Hodkiewicz Group"
            },
            "DebtorAccount": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "10000109010102",
                "Name": "John Doe"
            },
            "RemittanceInformation": {
                "Reference": "withdrawal",
                "Unstructured": "2490 quibusdam et omnis"
            }
        },
        "DomesticPaymentId": "obdsi-206dcf58e6f94f3f97d2246aca2d3dcb",
        "Refund": {
            "Account": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "10000109010102",
                "Name": "John Doe"
            }
        }
    },
    "Links": {
        "Self": "https://rs1.sbx.bam.com.gt/open-banking/v3.1/pisp/domestic-payments/obdsi-206dcf58e6f94f3f97d2246aca2d3dcb"
    },
    "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 7000: GET domestic-payments

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 `{{rs}}/open-banking/v3.1/pisp/domestic-payments/{{payment-id}}`

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)

Response

200 - Succesful

{
    "Data": {
        "ConsentId": "pay-di-8e20f314-141e-49c5-80c0-7b6e9a1ca6a2",
        "CreationDateTime": "2025-08-29T18:25:42.737Z",
        "StatusUpdateDateTime": "2025-08-29T18:25:48.632Z",
        "Status": "Pending",
        "Initiation": {
            "InstructionIdentification": "cXCN_DsVwOkaHhV",
            "EndToEndIdentification": "8SZU1iWT3xJNHd6",
            "InstructedAmount": {
                "Amount": "187.50",
                "Currency": "GTQ"
            },
            "CreditorAccount": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "00000020360961",
                "Name": "Hodkiewicz Group"
            },
            "DebtorAccount": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "10000109010102",
                "Name": "John Doe"
            },
            "RemittanceInformation": {
                "Reference": "withdrawal",
                "Unstructured": "2490 quibusdam et omnis"
            }
        },
        "DomesticPaymentId": "obdsi-206dcf58e6f94f3f97d2246aca2d3dcb",
        "Refund": {
            "Account": {
                "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                "Identification": "10000109010102",
                "Name": "John Doe"
            }
        },
        "MultiAuthorisation": {
            "Status": "AwaitingFurtherAuthorisation"
        }
    },
    "Links": {
        "Self": "https://rs1.sbx.bam.com.gt/open-banking/v3.1/pisp/domestic-payments/obdsi-206dcf58e6f94f3f97d2246aca2d3dcb"
    },
    "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

Response

200 - Succesful

400 - Bad Request

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

POST {{tokenEndpoint}}

Parameters

Valor de Variables

Response

200 - Succesful

400 - Bad Request

Paso 3. Método POST 2000: POST domestic-payment-consents

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

Parameters

Valores de Variables

IMPORTANTE Variables

Request Body Para Pago de Contado

Request Body Para Pago A Cuotas

Detalles de Request Body

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 Header 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

Response

200 - Succesful

400 - Bad Request

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

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

Parameters

Valores de Variables

Request Body

Valores de Variables Body

Response

201 - Consents Created

401 - Unauthorized

Paso 10. Método GET 7000: GET domestic-payments

GET {{rs}}/open-banking/v3.1/pisp/domestic-payments/{{payment-id}}

Parameters

Valores de Variables

Response

200 - Succesful

POST `{{tokenEndpoint}}`

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

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

POST `{{par-endpoint}}`

POST `{{tokenEndpoint}}`

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

GET `{{rs}}/open-banking/v3.1/pisp/domestic-payments/{{payment-id}}`