POST /challenge/$NONCE

This endpoint is used by the user-agent to submit the address to which a challenge should be sent by the challenger service.

Request:

Body should use the mime-type “application/x-www-form-urlencoded”. The posted form data must contain an address JSON object that follow the restrictions defined in config. If the address provided in the ChallengeSetupRequest of /setup was set to be read_only and that was subsequently returned in the ChallengeStatusResponse, then the body must not change that address, including preservation of the read_only field.

Response:

200 OK:

The response is ChallengeResponse. Since protocol v2.

400 Bad Request:

The request does not follow the spec. The response will include error code, hint and detail. Since protocol v1.

403 Forbidden:

The address being submitted differs from the previously submitted address but the validation process was set up as read_only and thus the address cannot be changed. Returned with TALER_EC_CHALLENGER_CLIENT_FORBIDDEN_READ_ONLY. Since protocol v4.

404 Not Found:

The service is unaware of a matching challenge. The response will include error code, hint and detail. Since protocol v1.

429 Too Many Requests:

There have been too many attempts to request challenge transmissions for this $NONCE. The user-agent should wait and (eventually) request a fresh nonce to be set up by the client. Returned with TALER_EC_CHALLENGER_TOO_MANY_ATTEMPTS. Since protocol v2.

500 Internal Server Error:

Server is not able to respond due to internal problems. The response will include error code, hint and detail. Since protocol v1.

502 Bad Gateway:

The challenger service failed to launch or communicate with its helper process for delivering the challenge (SMS, e-mail, postal mail). Returned with TALER_EC_CHALLENGER_HELPER_EXEC_FAILED.

// Union discriminated by the "type" field.
type ChallengeResponse = ChallengeRedirect | ChallengeCreateResponse

// @since **v2**
interface ChallengeRedirect {
  // Union discriminator field.
  type: "completed";

  // challenge is completed, use should redirect here
  redirect_url: string;
}

interface ChallengeCreateResponse {
   // Union discriminator field.
   type: "created"

   // how many more attempts are allowed, might be shown to the user,
   // highlighting might be appropriate for low values such as 1 or 2 (the
   // form will never be used if the value is zero)
   attempts_left: Integer;

   // the address that is being validated, might be shown or not
   address: Object;

   // true if we just retransmitted the challenge, false if we sent a
   // challenge recently and thus refused to transmit it again this time;
   // might make a useful hint to the user
   transmitted: boolean;

   // when we would re-transmit the challenge the next
   // time (at the earliest) if requested by the user
   // @since **v2**
   retransmission_time: Timestamp;
 }