Developer Portal
  • BAM Portal

Dispersión de Fondos

DISPERSIÓN DE FONDOS

La dispersión de fondos es el envío de dinero desde una cuenta central a varias cuentas destino, usado para pagos masivos como nóminas o proveedores. Puede ser interna entre BAM o interbancaria (bancos distintos), y puede hacerse al instante o programarse, según parámetros definidos y con consentimiento del usuario

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 anteriores.

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 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 3. 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
client_assertion_typeRequired String Header urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion Required String Header {{private_key_jwt}}

Valor de Variables

  • Tomar en cuenta el valor de {{tokenEndpoint}} y el resto de variables estara en el archivo .json que le comparte BAM al momento de su integracion.
  • Valor de {{private_key_jwt}} es igual a el valor responseBody que devuelve GET Prepare private key JWT.

Responses

200 - Succesful

{
    "access_token": "942c424c-438a-4ab0-92d1-700261d10eba",
    "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 4. Método POST2000: POST file-payment-consents

El endpoint POST /file-payment-consents permite al usuario solicitar a la entidad bancaria la creación de un recurso de consentimiento de pago por archivo sin necesidad de incluir datos de cuenta ni identificar todavía al titular de la cuenta. En la petición se envían los metadatos del consentimiento —es decir, el tipo de archivo (FileType) y el hash SHA-256 del fichero codificado en base64 (FileHash)— para que la entidad bancaria tenga la información necesaria. Una vez recibido, la entidad bancaria genera el recurso de consentimiento y devuelve un ConsentId único que el usuario usará para referirse a ese consentimiento en pasos posteriores.

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

Valores de Variables

  • Tomar en cuenta que el valor de {{rs}}, {{interactionId}} 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 {{tokenEndpoint}}
  • Valor de {{interactionId}} es un UUID de interacción que cambia con cada ejecucion.
  • Valor de {{hashPayloadData}} es el payload que se envía de una manera encriptada, este se prepara antes de ser enviado, ejemplo:
const dataPayload = JSON.stringify({
  "data": {
    "transaction": [
      {
        "originAccount": {
          "accountNumber": "0123456789",
          "accountType": "MONETARY",
          "currency": "GTQ"
        },
        "destinationAccount": {
          "accountNumber": "0123456789",
          "accountType": "SAVINGS",
          "currency": "GTQ",
          "email": "email@prueba.com"
        },
        "transferInfo": {
          "transactionType": "THIRD_BAM",
          "debitType": "D",
          "transactionAmount": 1.00,
          "executionType": "ONLINE",
          "concept": "Transferencia basica con todos los datos validos",
          "reference": "Se inserta el Consent ID"
        }
      }
    ]
  }
})

pm.environment.set('payload-payment-file-data', dataPayload)

const dataPayloadSigned = crypto.SHA256(dataPayload);

pm.environment.set('dataPayloadSigned', dataPayloadSigned)

pm.environment.set('hashPayloadData', 
    dataPayloadSigned.toString(crypto.enc.Base64));
  • Se bebe de construir un Json con los datos de Transacción el cual se envia como "{{payload-payment-file-data}}" ejemplo:
{
  "data": {
    "transaction": [
      {
        "originAccount": {
          "accountNumber": "0123456789",
          "accountType": "MONETARY",
          "currency": "GTQ"
        },
        "destinationAccount": {
          "accountNumber": "0123456789",
          "accountType": "SAVINGS",
          "currency": "GTQ",
          "email": "email@prueba.com"
        },
        "transferInfo": {
          "transactionType": "THIRD_BAM",
          "debitType": "D",
          "transactionAmount": 1.00,
          "executionType": "ONLINE",
          "concept": "Transferencia basica con todos los datos validos",
          "reference": "Se inserta el Consent ID"
        }
      }
    ]
  }
}

Request Body

{
  "Data": {
    "Initiation": {
      "SupplementaryData": {{payload-payment-file-data}},
      "FileType": "UK.OBIE.PaymentInitiation.4.0",
      "FileHash": "{{hashPayloadData}}",
      "FileReference": "GB2OK238",
      "NumberOfTransactions": "0",
      "ControlSum": 0
    }
  }
}

Responses

201 - Consents Created

{
    "Data": {
        "Initiation": {
            "SupplementaryData": {
                "Description": "Lorem ipsum"
            },
            "FileType": "UK.OBIE.PaymentInitiation.4.0",
            "FileHash": "61kyjpsLgyjwQgJSsPi4WPkVgMhAE4MzSQcJacNkAwk=",
            "FileReference": "GB2OK238",
            "NumberOfTransactions": "3",
            "ControlSum": 100
        },
        "ConsentId": "pay-fi-9c7f1bdb-4bb3-485f-99b1-e9040b09cdad",
        "Status": "AwaitingUpload",
        "CreationDateTime": "2025-06-18T17:31:05.292Z",
        "StatusUpdateDateTime": "2025-06-18T17:31:05.292Z"
    },
    "Links": {
        "Self": "https://rs1.sbx.bam.com.gt/open-banking/v3.1/pisp/file-payment-consents/pay-fi-9c7f1bdb-4bb3-485f-99b1-e9040b09cdad"
    },
    "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 5. Método POST200x: POST file-payment-consents/<consent-id>/file

Este endpoint facilita la subida de un archivo con los detalles de una operación de pago y, al recibirlo, verifica que su formato y contenido coincidan exactamente con lo acordado, garantizando así que no ha sido alterado. Si todo encaja, el fichero queda almacenado y listo para que el cliente lo revise y autorice el pago. En cambio, si se detecta cualquier discrepancia o error en el documento, la solicitud se rechaza de inmediato para evitar procesar datos no fiables. De este modo se asegura que solo se tramiten pagos basados en información validada y protegida.

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/file-payment-consents/{{intent-id}}/file

Parameters

Name Type Location Example Value
{{rs}} Required String Domain https://rs1.sbx.bam.com.gt
{{intent-id}} Required String Path Parameter pay-fi-ad64ada6-d473-4598-851a-9e043652b49b
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}}

Valores de Variables

  • Se bebe de construir un Json con los datos de Transacción el cual se envia como "{{payload-payment-file-data}}" ejemplo:
{
  "data": {
    "transaction": [
      {
        "originAccount": {
          "accountNumber": "0123456789",
          "accountType": "MONETARY",
          "currency": "GTQ"
        },
        "destinationAccount": {
          "accountNumber": "0123456789",
          "accountType": "SAVINGS",
          "currency": "GTQ",
          "email": "email@prueba.com"
        },
        "transferInfo": {
          "transactionType": "THIRD_BAM",
          "debitType": "D",
          "transactionAmount": 1.00,
          "executionType": "ONLINE",
          "concept": "Transferencia basica con todos los datos validos",
          "reference": "Se inserta el Consent ID"
        }
      }
    ]
  }
}

Valores de Variables

  • Tomar en cuenta que el valor de {{rs}}, {{interactionId}} estara en el archivo .json que le comparte BAM al momento de su integracion.
  • Valor de {{intent-id}} es igual a ConsentId que debuelve el paso POST {{rs}}/open-banking/v3.1/pisp/file-payment-consents
  • Valor de {{token-from-client-credentials-grant-payments}} es igual a el valor de access_token que devuelve en el paso POST {{tokenEndpoint}}
  • Valor de {{interactionId}} es un UUID de interacción que cambia con cada ejecucion.

Request Body

{
    {payload-payment-file-data}
}

Responses

201 - Consents Created

{
    "controlSum": 100,
    "numberOfTransactions": "3"
}

400 - Bad Request

{
    "Code": "UK.OBIE.Field.Invalid",
    "Message": "incorrect_records: check Records",
    "Errors": [
        {
            "ErrorCode": "UK.OBIE.Field.Invalid",
            "Message": "incorrect_records"
        }
    ]
}

Paso 6. Método POSTPOST 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

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

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 file-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:ae217cda-eaa2-45d1-ad1e-76f3d5e67f65",
    "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 7. 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: POST file-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 file-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

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 8. Método 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 9. Método POST5003: 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
grand_type Required String Body authorization_code
scope Required String Body payments
code Required String Body code
redirect_uri Required String Body https://www.auth-app.ozoneapi.co.uk/simple-redirect-url
code_verifier Required String Body {{code-verifier}}
client_assertion_type Required String Body urn:ietf:params:oauth:client-assertion-type:jwt-bearer
code_verifier Required String Body {{private_key_jwt}}

Valores de Variables

  • Valor de {{redirect_uri}} 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 {{private_key_jwt}} es igual a el valor del responseBody que devuelve el metodo GET Prepare private key JWT
  • 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": "fc8d695e-df01-4296-a7eb-ff1ebbd2d368",
    "expires_in": 432000,
    "token_type": "Bearer",
    "scope": "payments:pay-fi-e8acd724-71c7-43d7-943a-d75c6658437b openid",
    "state": "16649e6c-e51b-4919-ad7f-d9cf78448813",
    "refresh_token": "ee84307c-b7fb-4d93-9f28-c32215789410"
}

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 10 Método POST5003: POST Auth Code Grant (payments scope)

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/file-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 en Body

  • Valor de {{payment-consent-id}} es igual a el valor de ConsentId que se devuelve en POST 2000: POST file-payment-consents
  • Valor de {{Initiation}} es igual a el valor de {{Initiation}} que se devuelve en el metodo POST 2000: POST file-payment-consents:
{
      "SupplementaryData": {
          "Description": "Lorem ipsum"
      },
      "FileType": "UK.OBIE.PaymentInitiation.4.0",
      "FileHash": "{{hashPayloadData}}",
      "FileReference": "GB2OK238",
      "NumberOfTransactions": "3",
      "ControlSum": 100
}

Responses

- Consents Created

{
    "Data": {
        "ConsentId": "pay-fi-e8acd724-71c7-43d7-943a-d75c6658437b",
        "Status": "InitiationPending",
        "CreationDateTime": "2025-06-19T22:45:21.040Z",
        "StatusUpdateDateTime": "2025-06-19T22:45:21.040Z",
        "MultiAuthorisation": {
            "Status": "AwaitingFurtherAuthorisation"
        },
        "Initiation": {
            "SupplementaryData": {
                "Description": "Lorem ipsum"
            },
            "FileType": "UK.OBIE.PaymentInitiation.4.0",
            "FileHash": "61kyjpsLgyjwQgJSsPi4WPkVgMhAE4MzSQcJacNkAwk=",
            "FileReference": "GB2OK238",
            "NumberOfTransactions": "3",
            "ControlSum": 100
        },
        "FilePaymentId": "fp-1ace184ba02a43a1ba6bb8dd7c7d9615"
    },
    "Links": {
        "Self": "https://rs1.sbx.bam.com.gt/open-banking/v3.1/pisp/file-payments/fp-1ace184ba02a43a1ba6bb8dd7c7d9615"
    },
    "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 11. Método GET Step 7: GET 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/file-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}}

Valores de Variables

  • Valor de {{payment-id}} es igual a el valor FilePaymentId que devuelve POST Step 6: POST 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 {{tokenEndpoint}}

Responses

200 - File Payments Read

{
    "Data": {
        "ConsentId": "pay-fi-708c3ab3-736b-458e-a017-433c0b6cad08",
        "CreationDateTime": "2025-06-19T22:47:02.319Z",
        "StatusUpdateDateTime": "2025-06-19T22:47:06.583Z",
        "Status": "InitiationPending",
        "Initiation": {
            "SupplementaryData": {
                "Description": "Lorem ipsum"
            },
            "FileType": "UK.OBIE.PaymentInitiation.4.0",
            "FileHash": "61kyjpsLgyjwQgJSsPi4WPkVgMhAE4MzSQcJacNkAwk=",
            "FileReference": "GB2OK238",
            "NumberOfTransactions": "3",
            "ControlSum": 100
        },
        "FilePaymentId": "fp-f5351903f8e94f90b8e511b192f6d144"
    },
    "Links": {
        "Self": "https://rs1.sbx.bam.com.gt/open-banking/v3.1/pisp/file-payments/fp-f5351903f8e94f90b8e511b192f6d144"
    },
    "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"
        }
    ]
}

Paso 12. Método GETStep 7: GET file payment consent

El proveedor de servicios puede recuperar en cualquier momento el recurso de pago basado en archivo para conocer su estado, usando el {{payment-id}} . 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/file-payment-consents/{{intent-id}}

Parameters

Name Type Location Value
{{rs}} Required String Query Parameter https://rs1.sbx.bam.com.gt
{{intent-id}} Required String Query Parameter pay-fi-ad64ada6-d473-4598-851a-9e043652b49b
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-client-credentials-grant-payments}}

Valores de Variables

  • Valor de {{intent-id}} es igual a el valor de ConsentId que se devuelve en POST 2000: POST file-payment-consents
  • Valor de {{obParticipantId}} es igual a BAM
  • 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 {{tokenEndpoint}}

Responses

200 - File Payments Read

{
    "Data": {
        "Initiation": {
            "SupplementaryData": {
                "Description": "Lorem ipsum"
            },
            "FileType": "UK.OBIE.PaymentInitiation.4.0",
            "FileHash": "61kyjpsLgyjwQgJSsPi4WPkVgMhAE4MzSQcJacNkAwk=",
            "FileReference": "GB2OK238",
            "NumberOfTransactions": "3",
            "ControlSum": 100
        },
        "ConsentId": "pay-fi-708c3ab3-736b-458e-a017-433c0b6cad08",
        "Status": "Consumed",
        "CreationDateTime": "2025-06-19T22:45:59.277Z",
        "StatusUpdateDateTime": "2025-06-19T22:46:40.508Z"
    },
    "Links": {
        "Self": "https://rs1.sbx.bam.com.gt/open-banking/v3.1/pisp/file-payment-consents/pay-fi-708c3ab3-736b-458e-a017-433c0b6cad08"
    },
    "Meta": {}
}

401 - Unauthorized

{
    "Code": "UK.OBIE.Header.Missing",
    "Message": "missing_authorization_header: The authorization header is not specified.",
    "Errors": [
        {
            "ErrorCode": "UK.OBIE.Header.Missing",
            "Message": "missing_authorization_header: The authorization header is not specified.",
            "Path": "Authorization"
        }
    ]
}
Table of Content
Please wait